feat(memory): injecter le rappel mémoire dans le convention file à l'activation (§14.5.4)

À l'activation d'un agent, LaunchAgent compose désormais une section « # Mémoire projet » dans le convention file généré (CLAUDE.md/AGENTS.md…), au même titre que les skills assignés (§14.2). Les agents lisent ainsi la mémoire projet sans aucun flag ni mécanisme propre à une CLI. - LaunchAgent reçoit le port MemoryRecall (Arc<dyn MemoryRecall>), résout le rappel (budget AGENT_MEMORY_RECALL_BUDGET=2048, requête = persona de l'agent) en best-effort : mémoire vide/absente ou erreur ⇒ section omise, le launch n'est jamais bloqué (comme un SkillRef dangling). - compose_convention_file gagne un argument `memory: &[MemoryIndexEntry]` (reste pure) ; section injectée seulement pour la stratégie conventionFile. - state.rs : une seule instance NaiveMemoryRecall partagée (recall + LaunchAgent). Tests: 57 binaires verts. compose_convention_file (vide ⇒ inchangé, ordre, cohabitation skills) + intégration LaunchAgent (section présente / absente / best-effort sur erreur / pas d'injection en stratégie env). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-08 09:01:51 +02:00
parent 98a8b7292a
commit 2435857cbf
6 changed files with 484 additions and 26 deletions
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@ -616,7 +616,7 @@ IdeA/
 1. La **persona/rôle** de l'agent (son `.md` dans `.ideai/agents/`).
 2. Le **chemin absolu du project root** (pour que l'agent sache où opérer).
 3. Les **skills actifs** assignés à cet agent (voir §14.2).
-4. Une référence au **contexte projet partagé** si présent.
+4. Le **rappel mémoire** du projet (index/hooks), si présent (voir §14.5.4).

 **Avantages** :
 - Zéro collision entre agents, même N instances du même profil.
@ -702,6 +702,7 @@ Le **rappel** (port `MemoryRecall`) est adaptatif : tant que la taille de la mé
 - **LOT A — Étage 1 `.md`** : *domaine + adapter faits et verts.* Reste à livrer : **use cases `application/memory`** + **câblage app-tauri** (commandes + DTO ; les events `Memory*` et leurs DTO existent déjà). Voir §14.5.1.
 - **LOT B — Rappel adaptatif** : port `MemoryRecall`, adapter `NaiveMemoryRecall`, use case `RecallMemory`. Voir §14.5.2.
 - **LOT C — Étage 2 vectoriel** : port `Embedder`, profils déclaratifs `embedder.json`, adapter `VectorMemoryRecall`, logique de bascule sur seuil. Voir §14.5.3.
+- **Sous-lot d'intégration L14 ↔ L6** : injection du rappel mémoire dans le convention file à l'activation d'un agent (`LaunchAgent` compose `MemoryRecall`). Voir §14.5.4.

 ##### 14.5.1 LOT A (fin) — contrats application + app-tauri

@ -825,6 +826,76 @@ pub trait Embedder: Send + Sync {
 - **`EmbedderError`** : nouveau type d'erreur par port (façon `MemoryError`), mappé en `AppError` (`none`/indisponible ⇒ dégrade vers naïf, jamais d'échec dur du rappel).
 - **Garde-fou produit** : défaut `none` ⇒ LOT C **n'impose aucune dépendance** ; un utilisateur sans embedder a une mémoire pleinement fonctionnelle (étage 1 + rappel naïf).

+##### 14.5.4 Injection de la mémoire à l'activation d'un agent (intégration L14 ↔ L6)
+
+**Problème** : la mémoire (`MemoryStore` + `MemoryRecall`) existe et est consultable par commandes, mais **aucun agent ne la lit**. À l'activation d'un agent, IdeA génère le convention file (`CLAUDE.md`/`AGENTS.md`…) dans le run dir et y injecte la persona + les skills assignés (§14.1/§14.2) ; il faut y ajouter le **rappel mémoire** du projet, exactement comme les skills.
+
+**Décision (où injecter)** : le rappel est composé dans la **même fonction pure** `compose_convention_file`, qui devient :
+
+```rust
+pub(crate) fn compose_convention_file(
+    project_root: &str,
+    agent_md: &str,
+    skills: &[Skill],
+    memory: &[MemoryIndexEntry],   // nouveau : rappel mémoire (peut être vide)
+) -> String
+```
+
+- On passe les **`MemoryIndexEntry`** déjà résolus (pas une `&str` pré-rendue ni le port) : la fonction reste **pure et I/O-free**, donc unit-testable sans fake, cohérent avec le traitement des skills (le port est appelé en amont, pas dans la fonction de composition).
+- `LaunchAgent` gagne **une nouvelle dépendance port** `recall: Arc<dyn MemoryRecall>` (déjà un port domaine, déjà câblé en `NaiveMemoryRecall` dans `state.rs`). Aucun couplage à un adapter concret : Liskov garantit qu'un `VectorMemoryRecall`/`AdaptiveMemoryRecall` (LOT C) se substitue sans toucher à `LaunchAgent`.
+- La résolution suit le **modèle `resolve_skills`** : une méthode `resolve_memory(&self, root) -> Vec<MemoryIndexEntry>` best-effort appelée juste avant `apply_injection`, dont le résultat est passé à `apply_injection` puis à `compose_convention_file`. Signature interne :
+
+```rust
+async fn resolve_memory(&self, root: &ProjectPath) -> Result<Vec<MemoryIndexEntry>, AppError>;
+// puis :
+async fn apply_injection(
+    &self, project: &Project, context_rel_path: &str,
+    content: &MarkdownDoc, skills: &[Skill],
+    memory: &[MemoryIndexEntry],     // nouveau
+    spec: &mut SpawnSpec,
+) -> Result<(), AppError>;
+```
+
+**Décision (quoi injecter)** : l'**index/les hooks**, pas le corps des notes. On rappelle via `MemoryRecall::recall` (donc `read_index` tronqué au budget pour l'adapter naïf), et on rend une section :
+
+```markdown
+---
+
+# Mémoire projet
+
+- [Titre](slug.md) — hook (type)
+- …
+```
+
+Une ligne par `MemoryIndexEntry` (`title`, `slug`, `hook`, `r#type`). C'est le « léger par défaut » : l'agent reçoit les **pointeurs** vers le savoir projet (et peut lire le `.md` cible via son cwd = project root logique) ; l'étage 2 (corps/sémantique) reste hors convention file. Cohérent avec « léger par défaut, étage 2 seulement au-delà du seuil ».
+
+- **Budget** : constante `application` `const AGENT_MEMORY_RECALL_BUDGET: usize = 2_048;` (tokens approx.), passée dans `MemoryQuery { text, token_budget }`. Valeur **interne et documentée**, pas encore exposée en config (évolutif : pourra devenir un champ de réglage projet plus tard sans changer le contrat). `text` = la persona de l'agent (`content.as_str()`) : sans pertinence sémantique pour le naïf, mais déjà la bonne requête pour le vectoriel (LOT C) — zéro refactor au passage étage 2.
+
+**Décision (best-effort / dégradation)** : mémoire vide, absente, ou budget produisant 0 entrée ⇒ **aucune section `# Mémoire projet`** (omise entièrement, comme `# Skills` quand `skills` est vide) ⇒ document identique à l'actuel. `resolve_memory` ne **bloque jamais** un launch : le contrat de `MemoryRecall` est déjà « mémoire absente ⇒ liste vide, jamais d'erreur » ; une éventuelle `AppError::Store` inattendue est traitée comme les skills (best-effort — on dégrade vers liste vide plutôt que d'échouer l'activation). Confirmé : **un projet sans `.ideai/memory/` lance ses agents exactement comme aujourd'hui**.
+
+**Décision (universalité)** : l'injection passe **uniquement par le contenu du convention file** (`ContextInjectionPlan::File`), donc valable pour **toute stratégie `conventionFile`** (Claude/Codex/Gemini…), sans flag ni commande propriétaire. Pour `env`/`stdin`/`args` : **pas d'injection mémoire pour l'instant**, strictement **aligné sur les skills** (lesquels ne sont composés que dans la branche `File` de `apply_injection`). Rationale : l'uniformité avec les skills prime ; étendre aux autres stratégies serait une décision séparée (et pour `env`, la mémoire n'a pas de fichier unique à pointer). À tracer comme point ouvert si un profil non-`conventionFile` devait bénéficier du rappel.
+
+**Conformité hexagonale/SOLID** : `LaunchAgent` ne parle qu'à des **ports** (`+ Arc<dyn MemoryRecall>`) ; la composition reste une **fonction pure** ; aucun adapter concret référencé ; ISP respectée (une dépendance de plus, pour la seule tranche « rappel »). Substituabilité LOT C gratuite.
+
+**Découpage dev/test (ordre)** :
+
+1. `crates/application/src/agent/lifecycle.rs` — **dev** :
+   - ajouter le champ `recall: Arc<dyn MemoryRecall>` au struct `LaunchAgent` + paramètre dans `new` (en fin de liste, après `ids`) ;
+   - `const AGENT_MEMORY_RECALL_BUDGET: usize = 2_048;` ;
+   - `async fn resolve_memory(&self, root: &ProjectPath) -> Result<Vec<MemoryIndexEntry>, AppError>` (best-effort, dégrade vers `vec![]`) ;
+   - `execute` : appeler `resolve_memory` après `resolve_skills` et passer le résultat à `apply_injection` ;
+   - `apply_injection` : nouvel argument `memory: &[MemoryIndexEntry]`, transmis à `compose_convention_file` (branche `File` uniquement) ;
+   - `compose_convention_file` : nouvel argument `memory`, section `# Mémoire projet` (omise si vide), rendu d'une ligne par entrée.
+2. `crates/application/src/agent/lifecycle.rs` (`#[cfg(test)]`) — **test** : étendre les tests purs de `compose_convention_file` (section présente/ordonnée ; absente si vide ; document inchangé sans mémoire).
+3. `crates/app-tauri/src/state.rs` — **dev** : passer `Arc::clone(&memory_recall_port)` (existant l.509-510, à hisser avant la construction de `LaunchAgent` l.379) en dernier argument de `LaunchAgent::new`.
+4. **Câblage des tests existants** (`LaunchAgent::new` à 6 sites) — **test/dev** : fournir un fake `MemoryRecall` (un `FakeRecall` renvoyant `vec![]` par défaut, configurable pour un cas non-vide). Sites à mettre à jour :
+   - `crates/application/tests/agent_lifecycle.rs` (×5, dont l'helper de construction l.666) ;
+   - `crates/application/tests/orchestrator_service.rs` (l.407) ;
+   - `crates/infrastructure/tests/orchestrator_watcher.rs` (l.298).
+5. **Test d'intégration** (`agent_lifecycle.rs`) — **test** : avec un `FakeRecall` non-vide, asserter que le convention file écrit par `FakeFs` contient la section `# Mémoire projet` et les hooks ; avec recall vide, asserter son absence (document identique au baseline persona+skills).
+
+**Note de réutilisation** : la résolution préfère le port `MemoryRecall` (rappel borné) plutôt qu'un `read_index` brut, pour hériter directement de la bascule étage 1/étage 2 (LOT C) sans retoucher `LaunchAgent`.
+
 #### Anomalies de conformité relevées sur l'existant (à traiter par les agents dev)

 1. **Doublon `DomainError::MalformedFrontmatter` vs `MemoryError::Frontmatter`** : `error.rs` définit `DomainError::MalformedFrontmatter { reason }`, mais le domaine `memory.rs` ne l'utilise jamais (il lève `EmptyField`/`InvalidSlug`) et l'adapter parse via `MemoryError::Frontmatter`. La variante `DomainError::MalformedFrontmatter` est **morte**. **Action** : la supprimer (le parsing de frontmatter est une responsabilité d'adapter → `MemoryError::Frontmatter`), sauf si un futur parseur de frontmatter *dans le domaine* est prévu (il ne l'est pas — le domaine reste format-neutral, cf. doc-module `memory.rs`). Anomalie mineure, sans impact fonctionnel.