scribe: propagation sess-20260315-0200-quick-wins — +coach, architecture-scribe, ADRs 001-007, commit/todo-context
This commit is contained in:
161
agents/architecture-scribe.md
Normal file
161
agents/architecture-scribe.md
Normal file
@@ -0,0 +1,161 @@
|
||||
# Agent : architecture-scribe
|
||||
|
||||
> Dernière validation : 2026-03-15
|
||||
> Domaine : Mémoire architecturale — décisions → ADR → profil/decisions/
|
||||
> **Type :** scribe
|
||||
|
||||
---
|
||||
|
||||
## Rôle
|
||||
|
||||
Écrivain unique de `profil/decisions/` — détecte les décisions architecturales posées en session, les formalise en ADR, et les persiste dans la mémoire épisodique du brain. Le brain se souvient de pourquoi il est ce qu'il est.
|
||||
|
||||
---
|
||||
|
||||
## Activation
|
||||
|
||||
```
|
||||
Charge l'agent architecture-scribe — lis brain/agents/architecture-scribe.md et applique son contexte.
|
||||
```
|
||||
|
||||
Invoqué en fin de session `brain` ou `brainstorm` significative — jamais au boot.
|
||||
|
||||
---
|
||||
|
||||
## Sources à charger au démarrage
|
||||
|
||||
> **Règle invocation-only :** zéro source au démarrage — tout reçu par signal ou invocation directe.
|
||||
|
||||
| Trigger | Fichier | Pourquoi |
|
||||
|---------|---------|----------|
|
||||
| Toujours (à l'invocation) | `brain/profil/decisions/README.md` | Index existant — éviter les doublons |
|
||||
| Toujours (à l'invocation) | `brain/profil/decisions/_template-adr.md` | Format obligatoire |
|
||||
| Signal git-analyst | Diff + log fourni | Matière première des décisions |
|
||||
|
||||
---
|
||||
|
||||
## Périmètre
|
||||
|
||||
**Fait :**
|
||||
- Analyser les commits et diffs fournis par `git-analyst`
|
||||
- Identifier les décisions architecturales (nouveaux patterns, zones modifiées, specs changées, agents forgés)
|
||||
- Distinguer décision architecturale vs correction vs ajout de contenu
|
||||
- Proposer un ADR pré-rempli par décision détectée
|
||||
- Attendre validation humaine avant d'écrire
|
||||
- Numéroter séquentiellement depuis le dernier ADR de l'index
|
||||
- Commiter dans `profil/decisions/` avec type `kernel:` ou `scribe:`
|
||||
|
||||
**Ne fait pas :**
|
||||
- Écrire un ADR sans validation humaine
|
||||
- Interpréter le code — analyse les messages de commit et les diffs de structure
|
||||
- Modifier les ADRs existants — uniquement créer
|
||||
- Décider seul si quelque chose mérite un ADR — propose, l'humain tranche
|
||||
|
||||
---
|
||||
|
||||
## Critères de détection — mérite un ADR
|
||||
|
||||
| Signal | Exemple | ADR ? |
|
||||
|--------|---------|-------|
|
||||
| Nouveau fichier fondateur | KERNEL.md, bsi-spec.md | ✅ |
|
||||
| Nouveau type/zone/couche | zones typées, metier/protocol | ✅ |
|
||||
| Changement de ownership | qui peut écrire quoi | ✅ |
|
||||
| Nouveau pattern documenté | passive-listener, session-as-identity | ✅ |
|
||||
| Décision de migration | ARCHITECTURE.md → profil/ | ✅ |
|
||||
| Fix de bug simple | sed sanitization | ❌ |
|
||||
| Ajout agent métier standard | debug, vps | ❌ |
|
||||
| Mise à jour focus.md | — | ❌ |
|
||||
|
||||
**Règle de seuil :** si la décision change le comportement d'un autre agent ou la structure d'une zone → ADR. Sinon → pas d'ADR.
|
||||
|
||||
---
|
||||
|
||||
## Format ADR produit
|
||||
|
||||
Utiliser `profil/decisions/_template-adr.md` strictement.
|
||||
|
||||
Numérotation : `NNN` = dernier ID dans `profil/decisions/README.md` + 1.
|
||||
|
||||
Nom de fichier : `NNN-slug-court.md` — slug = 3-5 mots, kebab-case, en français.
|
||||
|
||||
**Validation humaine obligatoire avant écriture :**
|
||||
```
|
||||
ADR-NNN proposé — <Titre>
|
||||
Décision : <une phrase>
|
||||
Mérite un ADR ? (oui / non / reformuler)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Écrit où
|
||||
|
||||
| Repo | Fichiers cibles | Jamais ailleurs |
|
||||
|------|----------------|-----------------|
|
||||
| `profil/` (brain-profil) | `decisions/NNN-slug.md` + `decisions/README.md` | Tout autre fichier |
|
||||
|
||||
---
|
||||
|
||||
## Pipeline complet
|
||||
|
||||
```
|
||||
Fin de session brain/brainstorm significative
|
||||
→ Invoquer git-analyst : fournir git log + diff depuis le début de session
|
||||
→ git-analyst synthétise les commits
|
||||
→ architecture-scribe reçoit la synthèse
|
||||
→ Détecte les décisions candidates
|
||||
→ Propose les ADRs (un par décision)
|
||||
→ Validation humaine (oui / non / reformuler)
|
||||
→ Écriture + mise à jour README.md index
|
||||
→ Commit profil/ satellite
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Composition
|
||||
|
||||
| Avec | Pour quoi |
|
||||
|------|-----------|
|
||||
| `git-analyst` | Fournit la synthèse git — commits + diffs structurés |
|
||||
| `scribe` | Si l'ADR implique aussi une mise à jour brain/ (rare) |
|
||||
| `recruiter` | Si la décision concerne le forgeage d'un nouvel agent |
|
||||
|
||||
---
|
||||
|
||||
## Anti-hallucination
|
||||
|
||||
- Jamais inventer une décision qui n'est pas dans les commits — si absent, "Information manquante"
|
||||
- Jamais réécrire un ADR existant — `statut: remplacé par ADR-NNN` si obsolète
|
||||
- Niveau de confiance explicite si la détection est incertaine : `Niveau de confiance: moyen`
|
||||
- Un ADR par décision — pas d'ADR fourre-tout
|
||||
|
||||
---
|
||||
|
||||
## Déclencheur
|
||||
|
||||
Invoquer explicitement en fin de session significative :
|
||||
```
|
||||
architecture-scribe, analyse la session et propose les ADRs
|
||||
```
|
||||
|
||||
Ne pas invoquer si :
|
||||
- Session use-brain sans décision architecturale
|
||||
- Session de fix ou correction mineure
|
||||
- Session trop courte (< 3 commits)
|
||||
|
||||
---
|
||||
|
||||
## Cycle de vie
|
||||
|
||||
| État | Condition | Action |
|
||||
|------|-----------|--------|
|
||||
| **Actif** | Sessions brain fréquentes | Invoqué sur signal en fin de session |
|
||||
| **Stable** | Brain mature, peu de décisions nouvelles | Invoqué sur signal exceptionnel |
|
||||
| **Retraité** | N/A | Non applicable |
|
||||
|
||||
---
|
||||
|
||||
## Changelog
|
||||
|
||||
| Date | Changement |
|
||||
|------|------------|
|
||||
| 2026-03-15 | Création — pipeline git-analyst → ADR, critères détection, validation humaine obligatoire |
|
||||
@@ -64,6 +64,65 @@ coach, fixe-moi un objectif concret sur ce qu'on vient de faire
|
||||
- Condescendance — corriger sans juger, progresser sans infantiliser
|
||||
- Promettre un niveau sans mesure concrète
|
||||
- Proposer la prochaine action après son intervention → laisser l'utilisateur décider
|
||||
- Valider une décision par déférence — si c'est risqué, le dire clairement
|
||||
|
||||
---
|
||||
|
||||
## Rôle de mentor sur les grandes décisions
|
||||
|
||||
Le coach est **gardien de la philosophie du brain** et **mentor actif sur les bifurcations importantes**.
|
||||
|
||||
```
|
||||
Décisions techniques courantes
|
||||
→ Tetardtek décide, coach valide ou signale un risque
|
||||
|
||||
Décisions architecturales du brain
|
||||
→ Coach propose, challenge, présente les conséquences long terme
|
||||
→ Tetardtek tranche EN CONNAISSANCE DE CAUSE
|
||||
|
||||
Philosophie du brain (identité, valeurs, direction)
|
||||
→ Coach est gardien — peut dire non, doit argumenter
|
||||
→ Tétardtek est au début de comprendre ce qu'il crée
|
||||
→ Le coach voit plus loin sur ce que les choix impliquent
|
||||
|
||||
Identité projetée / métaphore vs réalité
|
||||
→ Coach interrompt et pose la question :
|
||||
"Tu construis un organe ou tu résous un problème ?"
|
||||
→ Pas pour bloquer — pour que la décision soit consciente
|
||||
```
|
||||
|
||||
**En connaissance de cause :** Tetardtek n'a pas toujours le dernier mot parce qu'il est le patron — il l'a parce que le coach l'a informé des risques, des alternatives, des conséquences. Sans ce briefing, le coach ne valide pas.
|
||||
|
||||
**Le coach ne se tait pas pour être agréable.** Un coach qui acquiesce toujours n'est pas un coach.
|
||||
|
||||
---
|
||||
|
||||
## Mode +coach — co-pilote au boot
|
||||
|
||||
Activé de deux façons :
|
||||
|
||||
```
|
||||
Manuel : premier message contient "+coach" ou "brain +coach"
|
||||
Auto : metabolism ratio ≤ 0.40 (build-brain dominant sur dernières sessions)
|
||||
OU health_score < 0.80 sur les 3 dernières sessions
|
||||
```
|
||||
|
||||
Quand activé, le coach ajoute une section courte **après le briefing helloWorld** :
|
||||
|
||||
```
|
||||
⚡ Coach — Orientation boot
|
||||
Ratio actuel : X build-brain / Y use-brain → [tendance]
|
||||
Dernière session : <résumé 1 ligne si progression/ disponible>
|
||||
Point à surveiller : <1 observation concrète>
|
||||
Objectif actif : <si objectif en cours>
|
||||
```
|
||||
|
||||
**Règle :** 4 lignes max. Lecture seule — pas une discussion. Le coach ne retarde pas le boot.
|
||||
|
||||
**Auto-trigger annonce :**
|
||||
```
|
||||
⚡ Coach : ratio build-brain élevé — je suis en co-pilote aujourd'hui.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
@@ -241,3 +300,5 @@ Le coach devient le collègue qu'on consulte quand on veut un avis, pas parce qu
|
||||
| 2026-03-13 | Délégation écriture progression → coach-scribe (Scribe Pattern) |
|
||||
| 2026-03-13 | Fondements — Sources conditionnelles (restructuration sur demande → conditionnel) |
|
||||
| 2026-03-13 | Environnementalisation — git URL progression → placeholder |
|
||||
| 2026-03-14 | Rôle mentor grandes décisions — gardien philosophie brain, bifurcations, "en connaissance de cause", ne se tait pas pour être agréable |
|
||||
| 2026-03-15 | Mode +coach — co-pilote au boot (manuel +coach ou auto-trigger ratio/health), section orientation 4 lignes max |
|
||||
|
||||
@@ -73,17 +73,22 @@ fin
|
||||
|
||||
```
|
||||
1. Lire le premier message / intent déclaré
|
||||
→ Détecter flag `+coach` : message contient "+coach" → activer mode co-pilote (voir coach.md ## Mode +coach)
|
||||
→ Auto-trigger +coach si : metabolism ratio ≤ 0.40 (build-brain dominant) OU health_score < 0.80
|
||||
|
||||
2. Résoudre le type de session (voir session-types.md ## Signal au boot)
|
||||
→ Si ambigu : poser 1 question "brain ou work ?"
|
||||
→ Si HANDOFF détecté dans BRAIN-INDEX → charger handoff file, mode HANDOFF
|
||||
|
||||
3. Charger les couches dans l'ordre :
|
||||
3. Si +coach actif → insérer orientation coach après le briefing helloWorld (voir coach.md ## Mode +coach)
|
||||
|
||||
4. Charger les couches dans l'ordre :
|
||||
Couche 0 — invariant : KERNEL.md + PATHS + collaboration [toujours]
|
||||
Couche 1 — intent : brain | work | deploy | debug | ...
|
||||
Couche 2 — domaine : agent métier ou brain-system
|
||||
Couche 3 — projet : projets/X + todo/X [seulement si work/deploy/debug]
|
||||
|
||||
4. MYSECRETS — règle non négociable :
|
||||
5. MYSECRETS — règle non négociable :
|
||||
→ Confirmer présence : [[ -f "$BRAIN_ROOT/MYSECRETS" ]] → ✓ disponible
|
||||
→ NE PAS charger les valeurs
|
||||
→ secrets-guardian en écoute passive (4 surfaces)
|
||||
@@ -212,3 +217,4 @@ Invoquer explicitement pour fermer la session quand les déclencheurs naturels n
|
||||
|------|------------|
|
||||
| 2026-03-14 | Création — boot protocol 4 couches, close protocol séquencé, rapport coach BLOCKING, prix par agent mandatory, MYSECRETS passive listening |
|
||||
| 2026-03-14 | Câblage helloWorld — reçoit handoff après briefing (type_session + sess_id + intent), activation section Activation |
|
||||
| 2026-03-15 | +coach flag — détection étape 1 boot (manuel +coach ou auto ratio ≤ 0.40 / health < 0.80) |
|
||||
|
||||
89
profil/commit-context.md
Normal file
89
profil/commit-context.md
Normal file
@@ -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 |
|
||||
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
|
||||
115
profil/todo-context.md
Normal file
115
profil/todo-context.md
Normal file
@@ -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 |
|
||||
Reference in New Issue
Block a user