Intelligence Layer — Les 4 Piliers

Comment Arc OS valide, apprend, se concentre et s'améliore.

Vue d'ensemble

L'Intelligence Layer s'intercale entre les messages utilisateur et les réponses Claude. Elle fonctionne en quatre étapes :

         INPUT                    PROCESSING                 OUTPUT
    ┌──────────────┐        ┌──────────────────┐       ┌─────────────────┐
    │ User Message  │───────►│  Context Router   │       │ Claude Response  │
    │               │        │  (skill scoring)  │       │  + eval warnings │
    │ Fix It / 👎   │        │                  │       │                 │
    │ (feedback)    │        │  Learnings       │       │ Quality metrics │
    │               │        │  (correction     │       │  logged         │
    └──────────────┘        │   injection)     │       └────────┬────────┘
                            │                  │                │
                            │  buildGsdPrompt()│        ┌───────┴────────┐
                            └────────┬─────────┘        │ Nightly Loop   │
                                     │                  │ (improvement   │
                                     ▼                  │  proposals)    │
                              Claude CLI                └────────────────┘

Pilier 1 : Binary Eval Engine

Quoi : Des règles déclaratives qui vérifient chaque réponse avant sa livraison.

Pourquoi : Les sorties IA doivent passer des contrôles qualité, comme des tests unitaires pour le code.

Comment :

Chaque skill peut avoir un fichier .evals.json avec des règles :

{
  "rules": [
    { "id": "gm-001", "type": "string_not_contains", "value": "--force", "severity": "warning" },
    { "id": "gm-002", "type": "max_length", "value": 4000, "severity": "info" }
  ]
}

Après que Claude génère une réponse, le moteur d'eval exécute toutes les règles applicables :

Pass : la réponse est livrée telle quelle
Fail : la réponse est livrée avec une note d'avertissement en bas de page

[Claude's response about git operations]
---
Eval: ⚠️ No force push | ℹ️ Response under 4000 chars

Types de règles

Type	Ce qui est vérifié
`string_contains`	La réponse doit inclure le texte littéral
`string_not_contains`	La réponse ne doit PAS inclure le texte
`regex_match`	La réponse doit correspondre au pattern regex
`regex_not_match`	La réponse ne doit PAS correspondre au regex
`max_length`	La réponse doit faire <= N caractères
`min_length`	La réponse doit faire >= N caractères

Décisions de conception clés

Non-bloquant : Les avertissements ne suppriment pas les réponses. Tu vois à la fois la réponse et le problème signalé.
Par skill : Des skills différentes ont des critères qualité différents.
Par projet : La même skill peut avoir des règles différentes selon les stacks techniques.
Pas d'IA dans la validation : Les règles sont déterministes. Résultat binaire pass/fail. Pas d'ambiguïté.

Référence de conception : Anthropic Skill Creator — evals structurées avec assertions binaires.

Pilier 2 : Context Router

Quoi : Sélection intelligente de skills qui n'injecte que les skills pertinentes dans chaque prompt.

Pourquoi : 25 skills chargées en même temps = dilution du contexte. Le modèle essaie d'appliquer des conseils de déploiement à des revues de code.

Comment :

Avant de construire le prompt, le router attribue un score à chaque skill enregistrée par rapport au message de l'utilisateur :

Score = (trigger matches x 2) + (keyword matches x 1)
Sort by score descending → take top 5

Exemple :

User: "Review this code for XSS vulnerabilities"

Scoring:
  code-review:     trigger "review" (2) + keyword "XSS" (1) = 3
  code-review-protocol: trigger "code review" (2)            = 2
  deployment-flow: no match                                  = 0
  git-manager:     no match                                  = 0

Injected into prompt:
  SKILLS_HINT (focus on these):
  - code-review: Security audit and code quality review...
  - code-review-protocol: Structured code review with OWASP...

Pourquoi consultatif et non filtrant

Le router suggère des skills mais n'en bloque pas d'autres. Claude conserve un accès complet.

Approche	Risque
Filtrage strict (`--allowedTools`)	Une mauvaise classification casse la session
Mutations par symlink	Modifications du système de fichiers sur un processus en cours
Hints consultatifs	Sûr : un mauvais hint = Claude l'ignore

Triggers vs Keywords

Triggers (2 pts) : Signaux d'invocation explicites. L'utilisateur demande directement cette capacité.

"deploy", "review", "scaffold", "audit"

Keywords (1 pt) : Contexte sémantique plus large. Suggère une pertinence sans être une commande.

"OWASP", "Docker", "CI/CD", "performance"

Référence de conception : Amorçage de contexte — attention ciblée sans filtrage strict.

Pilier 3 : Reflect Loop

Quoi : Capture automatique des corrections sous forme de règles persistantes.

Pourquoi : Les corrections IA doivent survivre aux redémarrages. Une correction = une amélioration permanente.

Comment :

CEO presses 🛠️ Fix It
    │
    ├── addLearning(source: "fixit", rule: "Fix requested for: <last response>")
    ├── projectLearnings reloaded from disk
    └── Fix prompt sent to Claude for immediate correction

CEO presses 👎
    │
    ├── addLearning(source: "negative", rule: "Negative feedback on: <response>")
    ├── qualityTracker.logFeedback(positive: false)
    └── projectLearnings reloaded from disk

Les règles sont stockées dans learnings.md :

# Learnings

## Rules

- [2026-04-03T14:22:00Z] [fixit] Always use t-call for translations in Odoo QWeb
- [2026-04-03T15:10:00Z] [negative] Avoid sudo in deployment scripts

À chaque message suivant, les learnings accumulés sont injectés :

LEARNINGS (past corrections — follow these rules):
- Avoid sudo in deployment scripts
- Always use t-call for translations in Odoo QWeb

Propriétés clés

Automatique : Pas d'écriture manuelle de règles. Appuie sur un bouton → règle créée.
Persistant : Survit aux redémarrages du bot. Écrit sur disque en Markdown.
Par projet : Chaque child bot a son propre learnings.md. Les corrections Odoo n'affectent pas le bot React.
Les plus récentes en premier : Les corrections les plus récentes ont la plus grande visibilité dans le prompt.
Budgété : Maximum 2000 caractères dans le bloc LEARNINGS. Les règles les plus anciennes sont écartées.

Référence de conception : Claude Reflect System — les corrections deviennent des règles permanentes qui préviennent les régressions.

Pilier 4 : Karpathy Loop

Quoi : Analyse nocturne automatisée des métriques qualité avec des propositions d'amélioration envoyées au CEO.

Pourquoi : Les humains oublient de surveiller les performances. Le système doit identifier ses propres points faibles.

Comment :

Chaque jour à 03h00 UTC, scripts/nightly-improve.ts s'exécute :

Lecture du registry — enumération de tous les child bots depuis bot_registry.json
Lecture des métriques — chargement de quality-metrics.json par child
Identification des sous-performants — filtrage des skills où :
- applied_count >= 3 (taille d'échantillon minimale pour éviter le bruit)
- ET soit success_rate < 80% SOIT feedback_negative > feedback_positive
Lecture des learnings — extraction des patterns de correction associés
Génération des propositions — basée sur des templates (déterministe, sans IA)
Envoi au CEO — rapport de synthèse + cartes de propositions individuelles sur Telegram

Flux d'approbation CEO

Telegram: Proposal Card
┌──────────────────────────────────────┐
│ Improvement Proposal                  │
│                                       │
│ Child: citadel-v2                     │
│ Skill: code-review                    │
│ Reason: low success rate (72%)        │
│ Feedback: 👍 4 / 👎 6                │
│                                       │
│ Related learnings:                    │
│   • Always use t-call for i18n        │
│                                       │
│ [✅ Approve]  [❌ Reject]             │
└──────────────────────────────────────┘

Approve : Sauvegarde skill.md → skill.v1.md (max 3 versions). Marqué comme approuvé.
Reject : Marqué comme rejeté dans proposals.json. Aucune modification effectuée.

Décisions de conception clés

Propositions basées sur des templates : Aucune IA ne génère les améliorations. Le système identifie le problème ; l'humain décide du correctif.
CEO dans la boucle : Pas de réécriture autonome de skills. Une approbation en un tap est requise.
Versioning des skills : Les sauvegardes préviennent la perte de données. Maximum 3 versions par skill.
Taille d'échantillon minimale : Les skills avec moins de 3 utilisations sont exclues de l'analyse (évite les faux positifs).

Référence de conception : Karpathy AutoResearch Loop — modifier → vérifier → conserver/écarter → répéter. Avec l'ajout critique de l'approbation humaine.

Comment les 4 piliers fonctionnent ensemble

Day 1:
  CEO sends message → Context Router suggests relevant skills
  Claude responds → Evals check output → Warning: "No force push"
  CEO sees warning, presses Fix It → Learning saved to learnings.md

Day 2:
  CEO sends similar message → Learnings injected: "Don't use --force"
  Claude avoids the mistake → No eval warnings → thumbs-up
  Quality metrics improve for that skill

Day 30:
  Nightly loop detects git-manager skill has 95% success rate
  No proposal needed — skill is healthy

Day 30 (different skill):
  Nightly loop detects code-review at 68% success
  Sends proposal to CEO → CEO approves → skill backed up
  CEO manually improves skill.md
  Next cycle: success rate climbs

Le système crée une boucle de rétroaction positive : les corrections deviennent des règles persistantes → les règles améliorent la qualité → les métriques reflètent l'amélioration → la boucle nocturne confirme la santé du système.

Pilier 5 : Sage Worker (Phase 40.11+)

Quoi : Analyse de skills alimentée par l'IA, benchmarking et découverte sur le marketplace.

Pourquoi : L'amélioration manuelle des skills ne passe pas à l'échelle. Il faut une analyse automatisée de la qualité des skills et un accès à l'expertise communautaire.

Comment :

Analyse de skill

Sélectionne n'importe quelle skill dans l'UI Skill Evolution → clique sur "Sage Analyze" → Sage (Claude Haiku) évalue :

La clarté et la complétude des instructions de la skill
La couverture des règles d'eval
Les recommandations d'amélioration

Benchmarks A/B

Compare deux versions d'une skill :

Sélectionne une mise à jour de skill (PR)
Lance le benchmark → Sage teste les deux versions sur des prompts d'exemple
Les résultats affichent une comparaison qualitative avec un résumé

Découverte sur le marketplace

Cherche des skills créées par la communauté sur claudemarketplaces.com :

"Sage Scout" → recherche par mot-clé
Analyse la compatibilité avec ton projet
Installe globalement ou fork vers un projet spécifique

Référence de conception : Gestionnaires de paquets (npm, pip) pour la gestion de skills IA, avec analyse de compatibilité alimentée par LLM.