--- name: bsi-schema type: reference context_tier: cold brain: version: 1 type: spec scope: kernel owner: human writer: human lifecycle: permanent read: full triggers: [] export: true --- # BSI Schema — Claim v1.3 > **Source unique du schema claim BSI versionné dans git.** > Protocole d'utilisation → `agents/satellite-boot.md` > Spécification complète (contexte, TTL, signals) → `profil/bsi-spec.md` (local, privé) > Registre live → `BRAIN-INDEX.md` --- ## Tous les champs d'un claim ```yaml # ── Champs obligatoires ──────────────────────────────────────────── sess_id: sess-YYYYMMDD-HHMM- # Identifiant unique de session type: pilote | satellite | solo # Rôle de la session scope: # Dossier ou fichier concerné (ex: agents/ ou agents/foo.md) agent: # Agent principal chargé (ex: helloWorld, satellite-boot) status: open | closed | stale # État courant opened_at: "YYYY-MM-DDTHH:MM" # ISO 8601 local # ── Champs optionnels — tous ─────────────────────────────────────── handoff_level: # Profondeur de handoff (0 = session fraîche) story_angle: # Angle narratif / description de la tâche # ── Champ multi-user (v2.3) — optionnel, prêt pour BaaS ─────────── # Absent = kerneluser implicite (brain owner, usage solo actuel). # Présent = identité explicite — filtrage BRAIN-INDEX, isolation zone:personal. # Convention : identifiant stable, pas de PII (username ou uuid opaque). # # user_id: # ex: tetardtek | client-42 # ── Champs optionnels — satellite uniquement (v1.3) ──────────────── satellite_type: code | brain-write | test | deploy | search | domain satellite_level: leaf | domain # Absent = leaf par défaut parent_satellite: # Lien vers pilote ou coordinateur parent # ── Champ calculé — close tier (v1.4, lecture seule) ─────────────── # close_tier est INFÉRÉ automatiquement — ne pas écrire dans le claim. # Tier 1 Atomic : leaf + satellite_type ∉ {code, test} # Tier 2 Validated : leaf + satellite_type ∈ {code, test} # Tier 3 Orchestrated: satellite_level=domain OU type=pilote # Protocole complet → agents/satellite-boot.md ## Close satellite — protocole tiered # ── Champs workflow (v1.9) — générés par workflow-launch.sh ─────── # workflow: # nom du workflow source # workflow_step: # numéro du step dans la chaîne # Ces champs permettent de tracer la position d'un satellite dans sa chaîne. # Workflow schema → workflows/_template.yml # Lancer le prochain step : bash scripts/workflow-launch.sh workflows/.yml # ── Mode rendering — instance autonome projet (v2.0) ────────────── # Déclaré dans le claim pilote pour activer le mode rendering de brain-compose. # Active : scope_lock (zone:project uniquement), circuit_breaker (3 fails → BLOCKED_ON), # et mutex BSI-v3-7 (file-lock.sh) avant chaque écriture. # # mode: rendering # scope: / ← seul périmètre autorisé — toute sortie = BLOCKED_ON immédiat # # Avant chaque écriture fichier : # bash scripts/file-lock.sh acquire "" "$sess_id" 30 # [écriture] # bash scripts/file-lock.sh release "" "$sess_id" # ── BSI-v3-7 — Mutex fichier (v2.0) ─────────────────────────────── # Empêche deux satellites d'écrire simultanément dans le même fichier. # Registre : locks/.lock # Usage : scripts/file-lock.sh acquire|release|check|list|cleanup # # Format lock : # file: # holder: # claimed_at: YYYY-MM-DDTHH:MM # expires_at: YYYY-MM-DDTHH:MM # ttl_min: (défaut: 60) # # Exit codes : 0=ok, 1=déjà locké (attendre), 2=release refusé (mauvais holder) # Comportement rendering : lock expiré → acquisition auto + log ⚠️ # ── Champ optionnel — theme branch (v1.8) ───────────────────────── # Branche git sur laquelle tous les satellites de ce thème commitent. # Convention : theme/ (ex: theme/brain-engine-be6) # Créer la branche : bash scripts/theme-branch-open.sh # Merger sur main : bash scripts/theme-branch-merge.sh # # theme_branch: theme/ # absent = main (défaut) # ── Champs optionnels — exit triggers (v1.7) ────────────────────── # Déclarés au lancement du satellite — lus au close par le pilote (aujourd'hui) # puis par kernel-orchestrator (BSI-v3-9). # # on_done: # result.status = ok # on_partial: # result.status = partial # on_fail: # result.status = failed # # Actions disponibles : # trigger → type: scope: # lancer le satellite suivant # signal → # envoyer un signal BSI # gate:human → "" # pause — confirmation humaine requise # notify → # INFO signal, pas de blocage # # Exemples : # on_done: trigger → type:test scope:brain-engine/ # on_partial: signal → CHECKPOINT pilote # on_fail: signal → BLOCKED_ON pilote # on_done: gate:human → "tests verts — deploy ?" # # Règles : # - on_done/on_partial/on_fail sont tous optionnels # - Si absent : comportement par défaut = signal CHECKPOINT pilote si pilote_id fourni # - gate:human suspend la chaîne — le pilote confirme avant que l'action suivante s'exécute # - Exécution actuelle : manuelle (pilote lit les triggers au close du satellite) # - Exécution future : automatique (kernel-orchestrator, BSI-v3-9) # ── Champ result — ajouté au close uniquement (v1.6) ────────────── # Écrit par le satellite au moment du close — jamais au boot. # Tier 1 Atomic : # result: # status: ok | partial | failed # files_modified: [, ...] # commit: # signal_id: | null # # Tier 2 Validated (+ tests) : # result: # status: ok | partial | failed # files_modified: [, ...] # tests: # total: # passed: # failed: # commit: # signal_id: | null # # Tier 3 Orchestrated (+ enfants agrégés) : # result: # status: ok | partial | failed # children: [, ...] # files_modified: [, ...] # commit: # signal_id: | null # notes: # # status: partial = livrable sorti mais incomplet — le pilote route différemment de ok/failed # ── Champ calculé — zone (v1.5, lecture seule) ───────────────────── # zone est INFÉRÉ depuis scope — ne pas écrire dans le claim. # zone: kernel → agents/, profil/, scripts/, KERNEL.md, brain-constitution.md, brain-compose.yml # zone: project → todo/, projets/, workspace/, handoffs/, infrastructure/, / # zone: personal → profil/capital.md, profil/objectifs.md, progression/, MYSECRETS # Règle d'autorisation → profil/decisions/014-zone-aware-bsi-kerneluser.md ``` --- ## Valeurs valides par champ ### `type` | Valeur | Description | |--------|-------------| | `pilote` | Session principale, contexte riche, décisions architecturales. Boot via `helloWorld`. | | `satellite` | Session focalisée, scope unique, tâche déléguée. Boot via `satellite-boot`. | | `solo` | Session autonome sans pilote — ni pilote ni satellite. | ### `status` | Valeur | Condition | Transition | |--------|-----------|------------| | `open` | Session active | → `closed` (close propre) ou `stale` (TTL expiré) | | `closed` | Fermée proprement | Terminal | | `stale` | TTL expiré sans fermeture | → suppression après contrôle humain | ### `satellite_type` | Valeur | Nature des modifications | |--------|--------------------------| | `code` | Code source d'un projet (hors brain/) | | `brain-write` | Fichiers brain : agents/, projets/, profil/, todo/, wiki/ | | `test` | Écriture ou exécution de tests | | `deploy` | Déploiement, ops, VPS, CI/CD, infra | | `search` | Audit, exploration, lecture seule ou quasi | | `domain` | Coordinateur de sous-domaine — peut lancer des satellites leaf | ### `satellite_level` | Valeur | Comportement | |--------|-------------| | `leaf` | *(défaut)* Tâche atomique. Ne lance pas de sous-satellites. | | `domain` | Coordinateur. Peut déléguer à des satellites leaf via `parent_satellite`. | ### `close_tier` (inféré — non écrit dans le claim) | Tier | Condition | Comportement au close | |------|-----------|-----------------------| | **Tier 1 — Atomic** | leaf + satellite_type ∉ {code, test} | Commit + close claim + signal retour | | **Tier 2 — Validated** | leaf + satellite_type ∈ {code, test} | Tests verts requis → commit + close + signal | | **Tier 3 — Orchestrated** | satellite_level=domain OU type=pilote | Attendre enfants fermés → agréger → close | --- ## Matrice de conflit `satellite_type × satellite_type` > Deux satellites concurrent sur le même scope. **Bloque** = le second doit attendre ou choisir un scope non-overlapping. | ↓ actif \ entrant → | `code` | `brain-write` | `test` | `deploy` | `search` | `domain` | |---------------------|--------|---------------|--------|----------|----------|----------| | `code` | ⚠️ Bloque | — | ⚠️ Bloque | ⚠️ Bloque | ✅ OK | ⚠️ Bloque | | `brain-write` | — | ⚠️ Bloque | — | — | ✅ OK | ⚠️ Bloque | | `test` | ⚠️ Bloque | — | ⚠️ Bloque | ⚠️ Bloque | ✅ OK | ⚠️ Bloque | | `deploy` | ⚠️ Bloque | — | ⚠️ Bloque | ⚠️ Bloque | ✅ OK | ⚠️ Bloque | | `search` | ✅ OK | ✅ OK | ✅ OK | ✅ OK | ✅ OK | ✅ OK | | `domain` | ⚠️ Bloque | ⚠️ Bloque | ⚠️ Bloque | ⚠️ Bloque | ✅ OK | ⚠️ Bloque | **Règles :** - `search` ne modifie pas les fichiers → jamais bloquant, jamais bloqué - Deux `brain-write` sur des fichiers **différents** dans le même dossier → pas de conflit (granularité fichier) - Deux `brain-write` sur le même fichier → conflit direct - `domain` vs `domain` → conflit systématique (coordinateurs parallèles sur même scope = risque élevé) --- ## Exemples de claims complets ### Claim pilote ```yaml sess_id: sess-20260316-2036-pilote-be5-wrap type: pilote scope: brain-engine/ agent: helloWorld status: open opened_at: "2026-03-16T20:36" handoff_level: 0 story_angle: "Pilote BE-5 wrap — claim close, README commit, suite satellite-boot-loader + BE-5e" ``` ### Claim satellite leaf ```yaml sess_id: sess-20260316-2046-bsi-v3-1 type: satellite scope: agents/ agent: satellite-boot status: closed opened_at: "2026-03-16T20:46" handoff_level: 0 story_angle: "BSI-v3-1 — ajouter satellite_type, satellite_level, parent_satellite dans le schema BSI claim" satellite_type: brain-write satellite_level: leaf parent_satellite: sess-20260316-2036-pilote-be5-wrap ``` ### Claim satellite avec exit triggers (v1.7) ```yaml sess_id: sess-20260316-2145-brain-engine-code type: satellite scope: brain-engine/ agent: satellite-boot status: open opened_at: "2026-03-16T21:45" story_angle: "Implémenter BE-6 feature X" satellite_type: code satellite_level: leaf parent_satellite: sess-20260316-2036-pilote-be5-wrap on_done: trigger → type:test scope:brain-engine/ on_partial: signal → CHECKPOINT pilote on_fail: signal → BLOCKED_ON pilote ``` *Au close, si result.status=ok → lance automatiquement un satellite test sur brain-engine/.* *Si failed → signal BLOCKED_ON vers le pilote, chaîne suspendue.* ### Claim satellite domain (coordinateur) ```yaml sess_id: sess-20260316-2100-superoauth-domain type: satellite scope: superoauth/ agent: satellite-boot status: open opened_at: "2026-03-16T21:00" handoff_level: 0 story_angle: "Coordonne les satellites leaf superoauth (audit + tests + deploy)" satellite_type: domain satellite_level: domain parent_satellite: sess-20260316-2036-pilote-be5-wrap ``` *Un satellite leaf lancé par ce domain déclare `parent_satellite: sess-20260316-2100-superoauth-domain`.* --- ## Changelog | Date | Version | Changement | |------|---------|------------| | 2026-03-16 | 1.3 | Création — schema complet, matrice de conflit, exemples pilote + leaf + domain | | 2026-03-16 | 1.4 | BSI-v3-5 — close_tier inféré (Atomic/Validated/Orchestrated) documenté dans schema | | 2026-03-16 | 1.5 | ADR-014 — zone inféré (kernel/project/personal) + modèle kerneluser | | 2026-03-16 | 1.6 | BSI-v3-2 — champ result: au close (status, files, tests, children, signal_id) | | 2026-03-16 | 1.7 | BSI-v3-3 — exit triggers : on_done/on_partial/on_fail + actions trigger/signal/gate:human/notify | | 2026-03-16 | 1.8 | BSI-v3-6 — theme_branch : theme/, scripts theme-branch-open/merge | | 2026-03-16 | 1.9 | BSI-v3-4 — workflow_step + workflow : champs claim générés par workflow-launch.sh | | 2026-03-16 | 2.0 | BSI-v3-7 — mutex fichier + mode:rendering : file-lock.sh, locks/, rendering mode claim | | 2026-03-16 | 2.1 | BSI-v3-8 — pre-flight check : 6 conditions (claim/scope/zone/lock/circuit-breaker/branch), kerneluser bypass | | 2026-03-16 | 2.2 | BSI-v3-5 — statuts waiting_human/paused, cascade pause/resume/abort, gate_history dans claim | | 2026-03-16 | 2.3 | Multi-user BaaS — champ user_id optionnel ancré (absent = kerneluser implicite) |