CLAUDE.md

1# OPC — Base de Connaissances Projet (Claude)
2 
3> Base de connaissances persistante lue par Claude à chaque session démarrée dans ce dépôt.
4> Centralise le contexte vital pour être opérationnel immédiatement, sans ré-explication.
5> Toute erreur ou préférence durable doit être consignée ici (apprentissage itératif).
6 
7**Dernière mise à jour :** 2026-06-22 — **v6.1.0** (ajout P11/P12 + décisions associées suite aux sprints 1-4 du hardening)
8 
9---
10 
11## Index rapide
12 
13| Besoin | Aller à |
14|---|---|
15| Démarrer une session | §18 |
16| Comprendre l'architecture | §1, §3 |
17| Connaître la stack | §2 |
18| Coder dans le loop agent | §7 + §16 |
19| Écrire un plugin | §1, §7 |
20| Modifier le shell Electron / IPC | §9, §13, §16 |
21| Committer proprement | §11 |
22| Déboguer un bug | §6 |
23| Éviter un piège connu | §7.4 (P1-P10) |
24| Vérifier avant PR | §10 |
25| Sécurité | §13 |
26| Mémoire & sauvegardes | §17 |
27 
28---
29 
30## 1. Identité du projet
31 
32OPC (Open Project Cockpit) est une **application desktop Electron + CLI Node/TypeScript** qui pilote un agent de coding autonome. Elle combine :
33 
34- une **boucle agentique** (act → observe → reason → repeat) de type ReAct ;
35- une couche **Human-in-the-Loop** via IPC Electron ;
36- un **système de plugins** inspiré de Claude Code ;
37- un bridge **CLI ↔ Electron** avec streaming d'événements JSON-lines.
38 
39La couche `src/` est principalement un **vendoring/fork de Claude Code upstream**. Toute la valeur ajoutée OPC vit dans `src/utils/` (loop), `desktop/electron/` (IPC) et `plugins/`.
40 
41---
42 
43## 2. Stack technique
44 
45Versions précises dans `package.json` (racine + `desktop/`). Spécificités à retenir :
46 
47- **TypeScript strict** côté `src/`, **CommonJS `.cjs`** côté `desktop/electron/` (mélanger ESM dans `desktop/` casse Electron).
48- **Trois `tsconfig` distincts**, tous `noEmit` (pas de bundle, `tsx` exécute directement) :
49 
50| Fichier | Périmètre |
51|---|---|
52| `tsconfig.check.json` | Typecheck global du refactor |
53| `tsconfig.utils.json` | Coeur loop (`src/utils/`) |
54| `tsconfig.loop-tests.json` | Tests loop (`src/utils/__tests__/`) |
55 
56- **Tests** : `node:test` natif (pas de framework tiers), via `npm run verify:ci`.
57- **Tooling** : Electron `^39.8.10`, electron-builder `^26.8.1`, Ink pour CLI React-like, `tsx ^4.22.4`.
58 
59---
60 
61## 3. Architecture des dossiers
62 
63| Dossier | Rôle |
64|---|---|
65| `src/utils/` | **Coeur OPC** : loop, budget, reasoner, context, humanGate, JSONL |
66| `src/utils/__tests__/` | Tests node:test (82 cas) |
67| `src/commands/`, `src/plugins/` | CLI + plugins utilisateur |
68| `desktop/electron/` | Shell Electron CommonJS strict (main, IPC, cliRunner, sessionStore) |
69| `desktop/test/`, `desktop/renderer/` | Tests Electron (310 cas) + UI navigateur |
70| `plugins/` | 16 plugins utilisateur (agent-sdk-dev, hookify, ...) |
71| `docs/` | Audits, specs, guides (référence clé : `docs/OPC_LOOP_ENGINEERING_AUDIT_2026-06-21.md`) |
72 
73---
74 
75## 4. Conventions de nommage
76 
77| Catégorie | Convention | Exemple |
78|---|---|---|
79| Fichiers TS | `kebab-case.ts` | `loopRunner.ts`, `contextBudget.ts` |
80| Fichiers CJS Electron | `camelCase.cjs` | `cliRunner.cjs`, `humanGateIpc.cjs` |
81| Composants JSX | `PascalCase.tsx` | `ConfirmationBanner.tsx` |
82| Tests | `<module>.test.ts` / `<module>.test.cjs` | `loopBudget.test.ts` |
83| Fonctions exportées | `camelCase` | `evaluateStop`, `dispatchReason` |
84| Types/Interfaces | `PascalCase` | `LoopEvent`, `Reasoner`, `BudgetTracker` |
85| Constantes globales | `UPPER_SNAKE` | `MAX_ITERS`, `DEFAULT_TIMEOUT_MS` |
86| Variables privées | préfixe `_` ou `private` TS | `_abortController` |
87| Branches git | `<type>-<scope>` en kebab-case | `opc-production-hardening` |
88 
89---
90 
91## 5. Skill actif : Fabuleux
92 
93**Obligatoire** pour toute tâche de livraison. Choisir le type :
94 
95| Type | Quand l'utiliser |
96|---|---|
97| Artefact | Code, composant, plugin, refactor |
98| Prose | Documentation, rédaction, README, CLAUDE.md |
99| Analyse | Recherche, comparaison, exploration |
100| Audit | Revue, diagnostic, post-mortem |
101 
102### 5.1 Boucle d'apprentissage (explicite)
103 
104```
105Produire     → 1ère passe du livrable (code, doc, analyse)
106   ↓
107Observer     → relire, vérifier la sortie réelle (lint/test/diff), comparer au but
108   ↓
109Capturer     → noter l'écart : bug, dérive, décision non documentée
110   ↓
111Corriger     → patcher + vérifier que le fix tient + mettre à jour CLAUDE.md si durable
112   ↓
113(rebouclage si écart restant)
114```
115 
116Règles absolues :
117 
1181. Pensée dense — réfléchir avant d'agir.
1192. Livrable fini — pas de placeholder, TODO, ni "à compléter".
1203. Auto-correction — relire systématiquement avant de répondre.
1214. Vérité objective — citer le résultat réel, pas l'espéré.
1225. **Note de confiance finale** obligatoire (haute / moyenne / basse) sur toute analyse ou audit.
123 
124---
125 
126## 6. Workflow standard
127 
128Pour chaque tâche de code :
129 
1301. **ORIENTER** — lire les fichiers concernés, `git status`, branche courante.
1312. **LIRE** — `read_file` sur TOUT ce qui sera modifié (jamais de mémoire).
1323. **PLANIFIER** — lister les changements AVANT de commencer.
1334. **EXÉCUTER** — changements ciblés, empreintes minimales.
1345. **VÉRIFIER** — `npm run verify:ci` (racine) + `npm --prefix desktop run verify:ci`.
1356. **COMMITTER** — Conventional Commits en français, scope explicite.
136 
137Pour les tâches ≥ 3 étapes : utiliser TodoWrite pour suivre l'avancement.
138 
139Pour le débogage : reproduire → chercher le message → cause racine → fix → chercher bugs similaires.
140 
141---
142 
143## 7. Coeur agent loop
144 
145Référence clé : `docs/OPC_LOOP_ENGINEERING_AUDIT_2026-06-21.md`.
146 
147Boucle principale : **Act → Observe → Verify → Reason → Repeat** avec bornes budgets.
148 
149### 7.1 Modules fondamentaux
150 
151| Fichier | Rôle | Exports clés |
152|---|---|---|
153| `src/utils/loopRunner.ts` | Orchestrateur principal | `runLoop`, `dispatchReason` |
154| `src/utils/loopBudget.ts` | BudgetTracker + sterile-action | `BudgetTracker`, `actionKey` |
155| `src/utils/loopStop.ts` | Critère d'arrêt central | `evaluateStop()` |
156| `src/utils/loopReasoner.ts` | ReAct pluggable (LLM ou heuristique) | `defaultReason`, `isTransientFailure` |
157| `src/utils/humanInTheLoop.ts` | Interface `HumanGate` | `noHumanGate`, `createIpcHumanGate` |
158| `src/utils/loopEvents.ts` | Union typée + emitter | `LoopEvent`, `LoopEventEmitter` |
159 
160Autres modules de support (events JSONL, context budget, vérification, criteria, tool registry, task checklist, memory) : voir arborescence `src/utils/` et `__tests__/`.
161 
162### 7.2 Décisions du reasoner (table de vérité)
163 
164| Cas | Décision | Effet |
165|---|---|---|
166| `act-fail` transient, attempt < 2 | `retry` | Compteur incrémenté |
167| `act-fail` déterminist (TypeError, ENOENT) | `escalate` | Sortie immédiate |
168| `act-fail` transient, confidence basse | `ask-human` | Prompt IPC |
169| `verify-ok` | `continue` (done) | Tâche marquée `done` |
170| `verify-fail` attempt ≤ 2 | `refine` | Texte tâche mis à jour |
171| `verify-fail` attempt > 2 | `ask-human` ou `escalate` | Selon confidence |
172| `human-approved` | `continue` | Override verify-fail |
173| `human-rejected` | `escalate` | Sortie immédiate |
174| `human-timeout` | `retry` | Compteur préservé |
175 
176### 7.3 Garanties boucle
177 
178Boucle **jamais bloquée** (timeout = pire cas borné), `defaultReason` toujours dispo en fallback, IPC safe (erreur résout `'timeout'`), `refine` commit immédiat avant le tour suivant.
179 
180### 7.4 Pièges connus (P1-P10)
181 
182> Lecture obligatoire avant toute modification loop ou IPC. Chaque piège cite la conséquence d'ignorance.
183 
184| # | Piège | Conséquence si ignoré |
185|---|---|---|
186| **P1** | **Émettre `loop_finished`** en fin de boucle, sans exception | Renderer reste sur "running" indéfiniment, l'utilisateur ne voit jamais l'état terminal |
187| **P2** | **`actionKey` du BudgetTracker** doit inclure un identifiant sémantique (tool + target + argsHash), pas juste le tool name | Les retries légitimes ne déclenchent pas la détection de boucle stérile → escalade absente |
188| **P3** | **Mettre à jour `tsconfig.utils.json` ET `tsconfig.loop-tests.json`** pour tout nouveau fichier `src/utils/*.ts` | Le nouveau module n'est pas typechecké ; les tests ne le voient pas ; CI silencieusement verte mais fausse |
189| **P4** | **Conserver le préfixe `opc:`** sur tous les canaux IPC `cliRunner.cjs` ↔ `loopEventIpc.cjs` | Renommer un canal casse le bridge CLI↔Electron silencieusement (événement jamais reçu côté renderer) |
190| **P5** | **Tests Electron en `.cjs`** : exécution via `node --test`, **pas via Electron** | Importer `electron` dans un test unit `.cjs` casse le runner ; les helpers doivent être neutres |
191| **P6** | **Boucle `while (true)` interdite** : utiliser `evaluateStop()` systématiquement | Risque de boucle infinie, dépassement budget, deadlock IPC |
192| **P7** | **Reasoner qui throw** : wrapper systématiquement dans try/catch + fallback `defaultReason` | Une exception LLM remonte jusqu'au renderer et casse la session |
193| **P8** | **IPC handler qui throw** : retourner `{ ok: false, error }`, ne jamais propager | Le renderer reçoit une exception non gérée ; état UI incohérent, pas de recovery |
194| **P9** | **Tests qui mockent le système de fichiers entier** : préférer `os.tmpdir()` + cleanup explicite | Tests qui passent en mock mais échouent en intégration ; pollution du repo |
195| **P10** | **Validation IPC obligatoire** via `desktop/electron/ipcValidation.cjs` : ne JAMAIS bypasser | Canal non validé = faille XSS, command injection ou path traversal exploitable depuis le renderer |
196| **P11** | **Buffers texte IPC/stream bornés** via `appendBoundedText(current, next, maxChars)` qui conserve la **queue** (`slice(-maxChars)`), pas la tête | Un stdout de loop agentique est un flux infini : garder le début = perdre toute l'info utile ; un buffer non borné = OOM et freeze IPC |
197| **P12** | **`webContents.send` toujours wrappé** via `createSendChannel({ getMainWindow, log })` qui no-op sur `mainWindow == null`, `mainWindow.isDestroyed()`, `webContents == null`, `webContents.isDestroyed()`, et qui swallow toute exception de `send()` | Renderer crashé ou fenêtre en cours de teardown → `send` jette synchroniquement, pollue les logs main-process et casse la session ; un canal non protégé = crash en cascade |
198 
199---
200 
201## 8. Profil d'une session réussie & indicateur de dérive
202 
203### 8.1 Profil d'une session bien conduite
204 
205Une session OPC conforme à ce baseline présente ces signaux :
206 
207| Signal | Indicateur |
208|---|---|
209| Lecture initiale | `CLAUDE.md` + fichiers touchés lus avant toute édition |
210| Plan | TodoWrite activé pour ≥ 3 étapes ; tâches marquées `in_progress` puis `completed` sans skip |
211| Vérification | `npm run verify:ci` ET `npm --prefix desktop run verify:ci` verts après chaque modification |
212| Livrable | Code complet (pas de `TODO`, pas de placeholder), note de confiance finale |
213| Mémoire | Pièges nouveaux capturés dans §7.4 (P1-P10) si récurrents |
214| Commit | Conventional Commits FR, scope explicite, tests verts en local |
215| Style | Réponses concises, pyramide inversée, chiffres plutôt qu'adjectifs |
216 
217### 8.2 Indicateur de dérive
218 
219Si **2 de ces signaux** sont absents, **stop & corriger** avant de continuer :
220 
221- ❌ Modification sans lecture préalable du fichier
222- ❌ Tests non lancés après changement de comportement
223- ❌ Livrable avec placeholder ou "à compléter"
224- ❌ Commit sans message conventionnel ou avec secrets en dur
225- ❌ Boucle d'apprentissage §5.1 non appliquée (pas d'observation, pas de correction)
226- ❌ Piège connu P1-P10 ignoré malgré rappel
227- ❌ Note de confiance absente sur analyse/audit
228- ❌ `console.log` laissé en production
229 
230---
231 
232## 9. Design & UX
233 
234Principes directeurs pour le shell Electron et le renderer OPC :
235 
236- **Latence perceptible** : tout délai > 200 ms doit être signalé (état transitoire visible).
237- **Confirmations destructrices** : suppression de session, kill de loop, reset budget → toujours via bannière (`ConfirmationBanner.js`) avec raison explicite.
238- **Stream JSONL** : le renderer doit afficher les événements au fil de l'eau, pas en bloc en fin de boucle.
239- **Couleurs sémantiques** : rouge = erreur/timeout, jaune = ask-human/en attente, vert = done, gris = idle.
240- **Accessibilité** : contrastes WCAG AA, navigation clavier pour les actions critiques (Enter = confirmer, Esc = annuler).
241- **Pas de blocking modal** : les bannières sont non-bloquantes ; le user peut continuer à lire le stream.
242 
243Référence : `desktop/renderer/services/confirmationBanner.js`, `desktop/renderer/services/sessionBanner.js`.
244 
245---
246 
247## 10. Système de vérification
248 
249### 10.1 Chaînes de vérif
250 
251| Commande | Périmètre |
252|---|---|
253| `npm run verify:ci` | `typecheck:refactor` + `typecheck:utils` + `typecheck:loop-tests` + `test:loop` + chaîne desktop |
254| `npm --prefix desktop run verify:ci` | `audit:security` (npm audit --audit-level=moderate --omit=optional) + `typecheck:refactor` + `test` (node --test test/*.test.cjs) |
255 
256### 10.2 Baselines à préserver
257 
258- **Tests loop** : `82/82` doivent rester verts (`src/utils/__tests__/`).
259- **Tests Electron** : `310/310` doivent rester verts (`desktop/test/*.test.cjs`).
260- **Typecheck** : `0 erreur` sur les 3 tsconfig.
261 
262Tout PR qui régresse l'un de ces seuils est **rejeté** sauf raison documentée.
263 
264---
265 
266## 11. Conventions de commit (Conventional Commits FR)
267 
268Format : `<type>(<scope>): <sujet>` + corps optionnel en français.
269 
270| Type | Usage |
271|---|---|
272| `feat` | Nouvelle fonctionnalité utilisateur |
273| `fix` | Correction de bug |
274| `refactor` | Refacto sans changement de comportement |
275| `docs` | Documentation seule |
276| `chore` | Maintenance (deps, config, CI) |
277| `perf` | Optimisation mesurable |
278| `test` | Ajout ou correction de tests |
279| `style` | Formatage seul |
280 
281---
282 
283## 12. Règles numérotées (1-12)
284 
285> Toutes les règles s'appliquent sans exception. Une règle enfreinte = livrable refusé.
286 
287### Senior génériques (R1-R5)
288 
2891. **Pas de catch silencieux** (`except: pass`, `catch(e) {}`) — toujours logger ou propager.
2902. **Pas d'`eval()`** avec des données utilisateur — risque d'injection.
2913. **Pas de `var`** — utiliser `const` par défaut, `let` si mutation nécessaire.
2924. **Pas de secrets hardcodés** — variables d'environnement, jamais en dur dans le code.
2935. **Pas de `rm -rf`** sans confirmation explicite — risque de destruction irréversible.
294 
295### Garde-fous VCS (R6)
296 
2976. **Pas de push vers `main`/`master`** sans tests verts en local + revue si branche partagée.
298 
299### Spécifiques OPC (R7-R11)
300 
3017. **Pas de `console.log` en production** — utiliser `loopEvents` ou `console.error`.
3028. **Pas de `any` TypeScript** — utiliser `unknown` + narrow (TS strict).
3039. **Toujours documenter les side-effects IPC** dans `preload.cjs` ET `ipcContract.cjs`.
30410. **Toujours émettre un `LoopEvent`** pour chaque transition d'état de la boucle.
30511. **Toujours valider les inputs aux frontières** (user input, IPC, API).
306 
307### Règle meta (R12)
308 
30912. **Ne jamais modifier CLAUDE.md en spéculation** — un ajout (règle, piège, décision) n'est consigné qu'**après validation explicite** par l'utilisateur ou après **deux occurrences confirmées** du même problème. Avant cela, le brouillon vit dans `.claude/MEMORY.md` ou dans le worklog de session.
310 
311---
312 
313## 13. Sécurité (revue systématique)
314 
315- **IPC validation** : `desktop/electron/ipcValidation.cjs` valide chaque canal. Ne JAMAIS bypasser (= piège P10).
316- **Path traversal** : résoudre tous les chemins via `path.resolve` puis vérifier préfixe autorisé.
317- **Command injection** : `cliRunner.cjs` doit passer par `execa`/`spawn` avec args en array, JAMAIS de `exec(string)`.
318- **Render XSS** : tout HTML injecté dans le renderer doit passer par un sanitizer (DOMPurify si dispo).
319- **Dependencies** : `audit:security` (moderate) doit rester clean avant tout PR.
320 
321---
322 
323## 14. Apprentissage itératif & décisions durables
324 
325> Cette section consigne les **décisions architecturales durables**. Les pièges récurrents sont centralisés en §7.4 (P1-P10) — ne pas dupliquer ici.
326 
327- `src/utils/` est en **TypeScript strict** avec `noEmit`. Pas de webpack/esbuild, **tsx** exécute directement. Toute tentative d'ajouter un bundler doit être justifiée.
328- **CommonJS strict** dans `desktop/electron/` (suffixe `.cjs`). Mélanger ESM dans `desktop/` casse Electron.
329- Les modules loop sont **sans dépendance externe runtime** : ils n'importent que des types Node natifs. C'est ce qui permet `tsconfig.utils.json` de typer sans `node_modules` complets.
330- `humanGateIpc.cjs` est **fail-safe par construction** : toute erreur résout `'timeout'`, jamais d'exception.
331- **Buffers texte bornés** (`appendBoundedText`, P11) : utiliser systématiquement pour stdout/stderr et tout flux infini susceptible de transiter par IPC ; exporter le helper depuis un module neutre pour réutilisation (cf. `cliRunner.cjs:129`).
332- **Tout `webContents.send` passe par `createSendChannel`** (P12) : import depuis `desktop/electron/sendChannel.cjs`, jamais d'appel direct à `mainWindow.webContents.send` depuis les handlers IPC ; garantit le no-op sûr sur fenêtre détruite et évite les exceptions silencieuses.
333 
334---
335 
336## 15. Glossaire
337 
338| Terme | Signification |
339|---|---|
340| ReAct | Pattern Reason + Act entrelacés à chaque tour |
341| HumanGate | Interface d'escalade humaine (`ask(payload) → approved/rejected/timeout`) |
342| BudgetTracker | Compteur tokens/USD/wall-time + détection de boucle stérile |
343| Sterile action | Action répétée sans progrès (≥ 3 fois) → escalade automatique |
344| `actionKey` | Clé sémantique pour détecter les repeats (`tool + target + argsHash`) |
345| `evaluateStop` | Fonction centrale de décision d'arrêt (abort / budget / fatal / done) |
346 
347---
348 
349## 16. Index des fichiers critiques
350 
351Pour toute intervention loop, **toujours lire ces fichiers en premier** :
352 
353```
354src/utils/loopRunner.ts                # orchestrateur
355src/utils/loopBudget.ts                # budget + sterile detection
356src/utils/loopStop.ts                  # evaluateStop
357src/utils/loopEvents.ts                # types d'événements
358src/utils/loopReasoner.ts              # ReAct
359src/utils/humanInTheLoop.ts            # interface HumanGate
360desktop/electron/ipc/humanGateIpc.cjs  # bridge IPC human
361desktop/electron/ipc/loopEventIpc.cjs  # bridge IPC events
362desktop/electron/cliRunner.cjs         # spawn CLI + stream JSONL
363docs/OPC_LOOP_ENGINEERING_AUDIT_2026-06-21.md  # état de l'art loop
364```
365 
366---
367 
368## 17. Mémoire de session
369 
370- **Mémoire projet long terme** : `.claude/MEMORY.md` (journal auto-généré, ne pas éditer à la main sauf décision durable).
371- **Mémoire personnelle utilisateur** : `~/.claude/CLAUDE.md` (chargée globalement, **priorité basse** par rapport à ce fichier).
372- **Mémoire globale projet** : `~/.claude/projects/-Users-bayeasssene-Documents-ProjetsGithub-OPC/memory/` (faits, feedback, references).
373 
374Pour une préférence durable (ex. "toujours valider avant commit"), demander **explicitement** "ajoute ça au CLAUDE.md" pour qu'elle soit consignée (cf. R12).
375 
376---
377 
378## 18. Démarrage rapide
379 
380```bash
381git status              # 1. État du repo
382npm run verify:ci       # 2. Référence : tout doit être vert
383```
384 
385Identifier le scope : `src/utils/*` (loop) | `desktop/electron/*` (IPC) | `plugins/*` (extension) | `docs/*` (audit/spec). Puis suivre §6.
386 
387### Workflow premier contact (5 min)
388 
3891. Lire §Index rapide → identifier les 2-3 sections pertinentes.
3902. Si intervention loop : §16 (fichiers critiques) → §7 (boucle) → §7.4 (pièges P1-P10).
3913. Si intervention IPC : §13 (sécurité) + §16 + piège P10.
3924. Lancer `verify:ci` (§10.1) pour baseline avant toute modification.
3935. Au moindre doute : §8.2 (indicateur de dérive) pour auto-évaluer.
394 
395---
396 
397*Confiance globale sur ce fichier : haute sur stack/architecture/baselines/pièges P1-P10 ; moyenne sur conventions de nommage et Design & UX (à confirmer sur l'ensemble du repo après 2-3 sessions d'usage).*