kernel: propagation KERNEL.md + architecture.md + decisions/ 5 ADRs
This commit is contained in:
@@ -1,5 +1,9 @@
|
||||
# ARCHITECTURE — Brain System
|
||||
|
||||
> Archivé dans `profil/architecture.md` — mémoire épisodique du brain.
|
||||
> Ce fichier reste à la racine comme point d'entrée lisible pour les humains et les forks.
|
||||
> La loi active du système est dans `KERNEL.md`.
|
||||
>
|
||||
> Rédigé : 2026-03-14 — pendant que c'est chaud.
|
||||
> Les décisions non-évidentes, les pourquoi, les trade-offs assumés.
|
||||
> Pour se souvenir dans 6 mois. Pour les gens qui fork.
|
||||
|
||||
162
KERNEL.md
Normal file
162
KERNEL.md
Normal file
@@ -0,0 +1,162 @@
|
||||
# KERNEL.md — Loi des zones
|
||||
|
||||
> **Type :** Invariant absolu — chargé Couche 0 par helloWorld, avant tout agent.
|
||||
> Dernière révision : 2026-03-14
|
||||
> Propriétaire : kernel (aucun agent ne modifie ce fichier seul — décision humaine requise)
|
||||
|
||||
---
|
||||
|
||||
## Principe fondateur
|
||||
|
||||
Le brain est une **matrice à zones typées avec protection graduée**.
|
||||
Chaque zone a une nature, une protection, et des scribes propriétaires.
|
||||
Un agent qui sait dans quelle zone il opère sait automatiquement ce qu'il peut écrire — et ce qu'il ne peut pas.
|
||||
|
||||
**Règle d'or — non négociable :**
|
||||
> Une feature grandit dans un satellite → elle peut être promue dans le kernel.
|
||||
> Le kernel ne dérive jamais vers un satellite. Le flux est unidirectionnel.
|
||||
|
||||
---
|
||||
|
||||
## Les zones
|
||||
|
||||
### ZONE KERNEL — Protection maximale
|
||||
|
||||
```
|
||||
Fichiers : KERNEL.md, CLAUDE.md, PATHS.md, brain-compose.yml, BRAIN-INDEX.md
|
||||
agents/ profil/
|
||||
```
|
||||
|
||||
| Règle | Détail |
|
||||
|-------|--------|
|
||||
| **Protection** | Aucun agent ne modifie sans décision humaine explicite |
|
||||
| **Versioning** | Chaque modification significative = tag semver |
|
||||
| **Export** | brain-template = kernel sans couche instance/personnelle |
|
||||
| **Commit type** | `kernel:` (contrat), `feat:` (nouvelle capacité), `bsi:` (claims/signals) |
|
||||
| **Scribe** | `scribe` (agents/, profil/ état), `orchestrator-scribe` (BRAIN-INDEX.md) |
|
||||
|
||||
**Sous-zone PROFIL — l'âme**
|
||||
```
|
||||
profil/ → Invariant (collaboration, kernel-zones, architecture) : jamais surchargé
|
||||
Contexte (session-types, agent-types, contexts/) : évolue sur signal validé
|
||||
Référence (bsi-spec, scribe-system) : mis à jour sur changement de spec
|
||||
```
|
||||
Le profil modèle la **personnalité** du brain. Un Invariant profil = valeur aussi dure que le kernel.
|
||||
|
||||
---
|
||||
|
||||
### ZONE SATELLITES — Vie libre, promotion possible
|
||||
|
||||
```
|
||||
Repos : toolkit/ progression/ todo/ reviews/
|
||||
handoffs/ workspace/
|
||||
```
|
||||
|
||||
| Règle | Détail |
|
||||
|-------|--------|
|
||||
| **Protection** | Chaque satellite a son scribe propriétaire — les autres ne touchent pas |
|
||||
| **Versioning** | Rythme propre à chaque satellite |
|
||||
| **Promotion** | Pattern validé dans toolkit/ → peut entrer dans profil/ ou agents/ via recruiter |
|
||||
| **Commit type** | `scribe:` `todo:` `metabolism:` `toolkit:` selon le satellite |
|
||||
| **Scribes** | toolkit-scribe, progression/metabolism-scribe, todo-scribe, coach-scribe |
|
||||
|
||||
---
|
||||
|
||||
### ZONE INSTANCE — Configuration machine
|
||||
|
||||
```
|
||||
Fichiers : focus.md, projets/*, PATHS.md (valeurs réelles), brain-compose.local.yml
|
||||
```
|
||||
|
||||
| Règle | Détail |
|
||||
|-------|--------|
|
||||
| **Protection** | Personnel à une machine — jamais dans brain-template |
|
||||
| **Commit type** | `scribe:` (focus, projets), `config:` (PATHS, compose) |
|
||||
| **Scribe** | `scribe` (focus, projets) |
|
||||
|
||||
---
|
||||
|
||||
### ZONE WORK — Externe
|
||||
|
||||
```
|
||||
Repos projets : GitHub, Gitea projets clients/perso
|
||||
```
|
||||
|
||||
| Règle | Détail |
|
||||
|-------|--------|
|
||||
| **Protection** | Aucune protection kernel — vit sa propre vie |
|
||||
| **Interaction** | Le brain documente, ne possède pas |
|
||||
|
||||
---
|
||||
|
||||
## Commit types — propriété et zone
|
||||
|
||||
| Type | Zone | Scribe propriétaire | Déclencheur |
|
||||
|------|------|--------------------|-|
|
||||
| `kernel:` | KERNEL | Décision humaine | Modification contrat fondateur |
|
||||
| `feat:` | KERNEL agents/ | recruiter + humain | Nouvel agent forgé, capacité ajoutée |
|
||||
| `fix:` | KERNEL agents/ | debug / agent-review | Correction comportement |
|
||||
| `bsi:` | KERNEL BRAIN-INDEX | orchestrator-scribe | Open/close claim, signal |
|
||||
| `scribe:` | INSTANCE + KERNEL profil/ | scribe | brain update (focus, projets, profil) |
|
||||
| `metabolism:` | SATELLITES progression/ | metabolism-scribe | Fin de session — métriques |
|
||||
| `todo:` | SATELLITES todo/ | todo-scribe | Intentions fermées/ouvertes |
|
||||
| `toolkit:` | SATELLITES toolkit/ | toolkit-scribe | Pattern validé en prod |
|
||||
| `config:` | INSTANCE | config-scribe | PATHS, compose, machine config |
|
||||
|
||||
**Règle scribe :**
|
||||
> Un agent métier ne commit jamais directement.
|
||||
> Il signal → le scribe compétent écrit → dans sa zone uniquement.
|
||||
|
||||
---
|
||||
|
||||
## Session type → zone access
|
||||
|
||||
| Type session | Zones accessibles | Zones interdites |
|
||||
|-------------|------------------|-----------------|
|
||||
| `brain` | KERNEL (agents/, profil/) | WORK |
|
||||
| `work` | KERNEL (lecture) + INSTANCE + SATELLITES | — |
|
||||
| `deploy` | KERNEL (lecture) + INSTANCE | progression/ |
|
||||
| `debug` | Toutes (lecture) + zone du bug | — |
|
||||
| `audit` | Toutes (lecture seule) | Écriture directe |
|
||||
| `coach` | SATELLITES progression/ | KERNEL (écriture) |
|
||||
| `brainstorm` | Toutes (lecture) + todo/ | KERNEL (écriture) |
|
||||
|
||||
---
|
||||
|
||||
## Protection graduée — niveaux
|
||||
|
||||
| Niveau | Fichiers | Peut modifier | Trigger |
|
||||
|--------|----------|---------------|---------|
|
||||
| **Absolu** | KERNEL.md, CLAUDE.md, bsi-spec.md | Humain uniquement | Décision architecturale majeure |
|
||||
| **Fort** | profil/ Invariant, agents/ system | Humain + confirmation | Session brain avec signal explicite |
|
||||
| **Standard** | agents/ metier, profil/ Contexte | Scribe sur signal | Fin de session significative |
|
||||
| **Libre** | Satellites, INSTANCE | Scribe propriétaire | En session, sur livrable |
|
||||
|
||||
---
|
||||
|
||||
## Règles d'inviolabilité
|
||||
|
||||
1. **KERNEL.md lui-même** — jamais modifié par un agent seul. Toujours décision humaine.
|
||||
2. **Profil Invariant** — jamais surchargé par une session de travail. Signal explicite requis.
|
||||
3. **Un scribe = un territoire** — toolkit-scribe ne touche pas progression/. Jamais.
|
||||
4. **Flux unidirectionnel** — satellite → kernel possible (promotion). Kernel → satellite = contamination.
|
||||
5. **Session audit** — lecture seule sur toutes les zones. Jamais d'écriture directe.
|
||||
|
||||
---
|
||||
|
||||
## Chargement
|
||||
|
||||
```
|
||||
helloWorld Couche 0 — invariant [toujours, avant tout agent] :
|
||||
KERNEL.md ← cette loi
|
||||
PATHS.md ← chemins machine
|
||||
profil/collaboration.md ← règles de travail
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Changelog
|
||||
|
||||
| Date | Changement |
|
||||
|------|------------|
|
||||
| 2026-03-14 | Création — zones typées, protection graduée, commit ownership, session→zone access |
|
||||
187
profil/architecture.md
Normal file
187
profil/architecture.md
Normal file
@@ -0,0 +1,187 @@
|
||||
# architecture.md — Mémoire des décisions fondatrices
|
||||
|
||||
> **Type :** Invariant — mémoire épisodique du brain
|
||||
> Propriétaire : lecture seule — jamais modifié rétroactivement, uniquement enrichi
|
||||
> Usage : brainstorm, content, compréhension du système par une nouvelle instance
|
||||
>
|
||||
> Rédigé : 2026-03-14 — pendant que c'est chaud.
|
||||
> Les décisions non-évidentes, les pourquoi, les trade-offs assumés.
|
||||
> Pour se souvenir dans 6 mois. Pour les gens qui fork.
|
||||
|
||||
---
|
||||
|
||||
## C'est quoi le brain
|
||||
|
||||
Un système de mémoire externe pour sessions Claude — persistent, versionné, multi-machine.
|
||||
|
||||
**Problème résolu :** Claude oublie entre les sessions. Le brain ne oublie pas.
|
||||
|
||||
**Ce que ça n'est pas :** un simple dossier de markdown. C'est un système avec des couches, des agents, des scribes, un protocole de coordination inter-sessions, et une logique de bootstrap.
|
||||
|
||||
---
|
||||
|
||||
## Les 3 couches — décision fondamentale
|
||||
|
||||
```
|
||||
KERNEL agents/, profil/
|
||||
Universel. Valable pour n'importe qui.
|
||||
Partagé entre toutes les instances via symlinks ou clone.
|
||||
→ brain-template est le kernel exportable.
|
||||
|
||||
INSTANCE focus.md, projets/, todo/, infrastructure/, PATHS.md
|
||||
Personnel à une machine / un contexte.
|
||||
Jamais dans le kernel. Jamais exporté tel quel.
|
||||
|
||||
PERSONNEL progression/, capital.md
|
||||
Intime. Jamais partagé, jamais forké.
|
||||
Une personne, un repo, aucun export.
|
||||
```
|
||||
|
||||
**Pourquoi 3 couches et pas 2 ?**
|
||||
La ligne kernel/personnel est évidente. La couche instance est moins intuitive — elle existe parce qu'un même kernel peut tourner sur plusieurs machines avec des configs radicalement différentes (chemins, services, projets). Sans instance, on hardcode dans le kernel. Le kernel pollue. L'export devient impossible.
|
||||
|
||||
---
|
||||
|
||||
## Les repos satellites — décision architecture
|
||||
|
||||
Le brain n'est pas un monorepo. Chaque couche a son repo :
|
||||
|
||||
| Repo | Chemin local | Couche | Push vers |
|
||||
|------|-------------|--------|-----------|
|
||||
| `brain` | `/home/tetardtek/Dev/Docs/` | Kernel + instance | Gitea privé |
|
||||
| `brain-profil` | `Docs/profil/` | Kernel (profil perso) | Gitea privé |
|
||||
| `brain-todo` | `Docs/todo/` | Instance | Gitea privé |
|
||||
| `brain-toolkit` | `Docs/toolkit/` | Instance (patterns) | Gitea privé |
|
||||
| `brain-progression` | `Docs/progression/` | Personnel | Gitea privé |
|
||||
| `brain-agent-review` | `Docs/reviews/` | Instance (audits) | Gitea privé |
|
||||
|
||||
Tous gitignorés dans `brain/` sauf leur propre `.git/`.
|
||||
|
||||
**Pourquoi des repos séparés ?**
|
||||
- Rythme de commit différent : `todo/` change tous les jours, `profil/` change rarement
|
||||
- Exportabilité granulaire : on peut partager `profil/` sans exposer `todo/` ou `progression/`
|
||||
- Isolation des accès : un collaborateur peut avoir accès à `reviews/` sans voir `progression/`
|
||||
- Chaque scribe commit dans son repo — responsabilité claire, historique lisible
|
||||
|
||||
---
|
||||
|
||||
## Le pattern `.env` du brain
|
||||
|
||||
Même logique qu'un projet dev :
|
||||
|
||||
```
|
||||
brain-compose.yml → .env.example (versionné, valeurs génériques)
|
||||
brain-compose.local.yml → .env (gitignored, valeurs machine réelles)
|
||||
CLAUDE.md.example → .env.example (versionné, template avec <PLACEHOLDERS>)
|
||||
~/.claude/CLAUDE.md → .env (non versionné, config live)
|
||||
PATHS.md → .env (chemins réels de cette machine)
|
||||
```
|
||||
|
||||
**La règle :** toute valeur qui change selon la machine vit dans un fichier gitignored ou dans le fichier local de la couche. Jamais hardcodée dans le kernel.
|
||||
|
||||
---
|
||||
|
||||
## Pourquoi helloWorld plutôt qu'un bootstrap statique
|
||||
|
||||
Le bootstrap statique (lire focus.md + tous les agents au démarrage) charge trop, charge à l'aveugle, ne s'adapte pas au contexte.
|
||||
|
||||
helloWorld fait mieux :
|
||||
|
||||
```
|
||||
Bootstrap statique helloWorld
|
||||
───────────────── ──────────────────────────
|
||||
Charge tout au démarrage Charge le minimum
|
||||
Ignore le contexte Détecte le type de session
|
||||
Ignore les feature flags Filtre les agents par tier
|
||||
Ignore BRAIN-INDEX.md Scanne le CHECKPOINT avant tout
|
||||
Statique Adaptatif
|
||||
```
|
||||
|
||||
**Trade-off assumé :** helloWorld est un agent comme les autres — il peut halluciner, rater un signal. Le bootstrap statique était déterministe. On a choisi l'adaptabilité sur la déterminisme, parce que le brain est devenu trop grand pour être chargé en entier à chaque session.
|
||||
|
||||
---
|
||||
|
||||
## BSI — Brain Session Index
|
||||
|
||||
Problème : plusieurs sessions en parallèle peuvent modifier les mêmes fichiers sans se voir.
|
||||
|
||||
Solution : `BRAIN-INDEX.md` — registre de claims + bus de signaux.
|
||||
|
||||
```
|
||||
## Claims actifs → scribe uniquement — qui travaille sur quoi
|
||||
## Signals → orchestrator-scribe uniquement — messages inter-sessions
|
||||
## Historique → audit trail — ce qui s'est passé
|
||||
```
|
||||
|
||||
**Locking optimiste + TTL :** on ne bloque pas, on déclare. Si deux sessions se croisent, le watchdog détecte et alerte. L'humain décide.
|
||||
|
||||
**CHECKPOINT :** signal spécial A→A. Une session se snapshote elle-même dans BRAIN-INDEX.md. La session suivante (ou la même après compactage LLM) relit le checkpoint et reprend exactement là où c'était. Persisté dans git — survit à tout.
|
||||
|
||||
---
|
||||
|
||||
## Session-as-identity — pourquoi pas de fork par rôle
|
||||
|
||||
Problème initial : plusieurs rôles en parallèle (build, review, test) → on forke un brain par rôle → explosion de configs.
|
||||
|
||||
Solution : le slug de session IS l'identité de routage.
|
||||
|
||||
```
|
||||
sess-20260314-0900-build@desktop → rôle build
|
||||
sess-20260314-0901-review@desktop → rôle review
|
||||
sess-20260314-0902-test@desktop → rôle test
|
||||
```
|
||||
|
||||
Un seul brain par machine. N sessions nommées. orchestrator-scribe route les signaux par `sess-id@machine` (message direct) ou `brain_name@machine` (broadcast).
|
||||
|
||||
---
|
||||
|
||||
## Le Scribe Pattern — principe de non-contamination
|
||||
|
||||
Règle dure : un agent métier n'écrit jamais directement dans le brain.
|
||||
|
||||
```
|
||||
Agent métier → signal → scribe compétent → write
|
||||
```
|
||||
|
||||
Sans ça : chaque agent écrit partout → dérive garantie.
|
||||
Avec ça : chaque scribe est le seul responsable de son territoire.
|
||||
|
||||
8 scribes, 8 territoires exclusifs. Voir `profil/scribe-system.md` pour la carte complète.
|
||||
|
||||
---
|
||||
|
||||
## brain-template — le kernel exportable
|
||||
|
||||
`brain-template` = le kernel sans la couche instance et sans la couche personnelle.
|
||||
|
||||
```
|
||||
brain-template/
|
||||
agents/ ← tous les agents universels (zéro valeur perso)
|
||||
profil/ ← profil universel (anti-hallucination, spec, patterns)
|
||||
BRAIN-INDEX.md ← vide
|
||||
brain-compose.yml ← spec versionnée
|
||||
PATHS.md ← template avec <PLACEHOLDERS>
|
||||
focus.md ← starter
|
||||
README.md ← procédure d'installation complète
|
||||
```
|
||||
|
||||
**Versioning :** semver `v0.x.x` — kernel en évolution. `v1.0.0` quand l'interface est contractuelle.
|
||||
**Distribution :** repo Gitea privé aujourd'hui. GitHub public quand v1.0.0 validé.
|
||||
|
||||
---
|
||||
|
||||
## Ce qui n'est pas dans ce doc
|
||||
|
||||
- Comment créer un agent → `agents/_template.md`
|
||||
- Comment les scribes fonctionnent → `profil/scribe-system.md`
|
||||
- La spec BSI complète → `profil/bsi-spec.md`
|
||||
- Les patterns d'orchestration → `profil/orchestration-patterns.md`
|
||||
- Les règles de collaboration → `profil/collaboration.md`
|
||||
|
||||
---
|
||||
|
||||
## Changelog
|
||||
|
||||
| Date | Changement |
|
||||
|------|------------|
|
||||
| 2026-03-14 | Création — première ARCHITECTURE.md du brain, décisions non-évidentes documentées pendant que c'est chaud |
|
||||
25
profil/decisions/README.md
Normal file
25
profil/decisions/README.md
Normal file
@@ -0,0 +1,25 @@
|
||||
# decisions/ — Architecture Decision Records
|
||||
|
||||
> **Type :** Invariant — mémoire des choix architecturaux datés
|
||||
> Format : ADR (Architecture Decision Record)
|
||||
> Propriétaire : architecture-scribe (à forger) + décision humaine
|
||||
>
|
||||
> Jamais modifié rétroactivement. Uniquement enrichi.
|
||||
> Un ADR décrit : contexte → décision → conséquences.
|
||||
|
||||
---
|
||||
|
||||
## Index
|
||||
|
||||
| ID | Date | Décision | Statut |
|
||||
|----|------|----------|--------|
|
||||
| 001 | 2026-03-14 | Locking optimiste BSI — claims + TTL vs mutex strict | actif |
|
||||
| 002 | 2026-03-14 | Session-as-identity — slug session IS le rôle, pas de fork par rôle | actif |
|
||||
| 003 | 2026-03-14 | Scribe Pattern — non-contamination, un scribe = un territoire | actif |
|
||||
| 004 | 2026-03-14 | 3 couches kernel/instance/personnel — séparation exportabilité | actif |
|
||||
| 005 | 2026-03-14 | Zones typées + protection graduée — KERNEL.md comme loi active | actif |
|
||||
|
||||
---
|
||||
|
||||
> Format fichier : `NNN-slug-court.md`
|
||||
> Template : voir `_template-adr.md`
|
||||
42
profil/decisions/_template-adr.md
Normal file
42
profil/decisions/_template-adr.md
Normal file
@@ -0,0 +1,42 @@
|
||||
# ADR-NNN — <Titre court>
|
||||
|
||||
> Date : YYYY-MM-DD
|
||||
> Statut : proposé | actif | dépassé | remplacé par ADR-NNN
|
||||
> Décidé par : <humain / session brain / brainstorm>
|
||||
|
||||
---
|
||||
|
||||
## Contexte
|
||||
|
||||
<Quel problème existait ? Pourquoi une décision était nécessaire ?>
|
||||
|
||||
---
|
||||
|
||||
## Décision
|
||||
|
||||
<Ce qui a été décidé. Une phrase claire.>
|
||||
|
||||
---
|
||||
|
||||
## Alternatives considérées
|
||||
|
||||
| Option | Raison du rejet |
|
||||
|--------|----------------|
|
||||
| | |
|
||||
|
||||
---
|
||||
|
||||
## Conséquences
|
||||
|
||||
**Positives :**
|
||||
-
|
||||
|
||||
**Négatives / trade-offs assumés :**
|
||||
-
|
||||
|
||||
---
|
||||
|
||||
## Références
|
||||
|
||||
- Fichiers concernés :
|
||||
- Sessions où la décision a émergé :
|
||||
Reference in New Issue
Block a user