From f9231422fed7d4b673ccc78a2f26c156d8b34797 Mon Sep 17 00:00:00 2001 From: Blomios Date: Mon, 22 Jun 2026 12:29:44 +0200 Subject: [PATCH] =?UTF-8?q?docs(adr):=20contrat=20futur=20du=20seam=20LLM?= =?UTF-8?q?=20de=20r=C3=A9sum=C3=A9=20de=20handoff=20(LS5)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ADR brève : borne summary_md et point d'extension LLM (non activé). Co-Authored-By: Claude Opus 4.8 --- .../LS5-handoff-summary-bound-and-llm-seam.md | 38 +++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 docs/adr/LS5-handoff-summary-bound-and-llm-seam.md diff --git a/docs/adr/LS5-handoff-summary-bound-and-llm-seam.md b/docs/adr/LS5-handoff-summary-bound-and-llm-seam.md new file mode 100644 index 0000000..b0d030b --- /dev/null +++ b/docs/adr/LS5-handoff-summary-bound-and-llm-seam.md @@ -0,0 +1,38 @@ +# ADR LS5 — Borne du résumé de handoff & seam résumeur LLM + +Statut : accepté (lot LS5, branche `feature/agent-live-state`). + +## Contexte + +Le résumé de reprise (`Handoff::summary_md`) est injecté dans le contexte d'un agent +à **chaque lancement** et persisté à **chaque checkpoint**. Sans borne, un gros tour +`Response` produit une ligne géante qui gonfle le résumé → coût sur le **chemin chaud** +(append/checkpoint + contexte injecté). Priorité produit : gagner en perf **sans** mettre +de LLM sur ce chemin chaud. + +## Décision (implémentée) + +1. **Borne par ligne (infra)** : `render_turn` tronque le texte aplati de chaque tour à + `TURN_LINE_MAX_CHARS = 240` (élision `…`), préfixe `- **role:**` conservé. Correctif + central du trou de perf. +2. **Borne universelle (domaine)** : `bound_handoff_summary(h, HANDOFF_SUMMARY_MAX_CHARS=4096)`, + pure, idempotente, sans rejet — garde l'objectif + le suffixe de tours le plus récent, + droppe les plus anciens, hard-truncate la fin d'une ligne trop longue sans casser son + préfixe. `up_to`/`objective` jamais modifiés. +3. **Application** : la borne universelle est posée **entre `fold` et `save`** (écriture) + et **avant `compose_convention_file`** (injection, protège les `handoff.md` legacy). + Indépendante du résumeur. + +## Seam LLM — futur, NON implémenté + +Le port `HandoffSummarizer::fold` reste **inchangé** (async, sans `Result`, best-effort) ; +le défaut câblé reste `HeuristicHandoffSummarizer`. Un futur `LlmHandoffSummarizer` devra +respecter le contrat suivant : + +- **Hors chemin chaud, déclenchement froid** : jamais par tour. Calcul à la reprise / à la + rotation / sur débounce (coalescer plusieurs tours rapides), pas à chaque `record`. +- **Timeout + fallback heuristique** : un appel réseau lent/échoué retombe sur le résumé + heuristique (ou `prev`), jamais d'erreur propagée, jamais de blocage du checkpoint. +- **Sélection par flag**, défaut **heuristique** (zéro dépendance réseau par défaut). +- La **borne universelle** s'applique de toute façon à sa sortie (garantie indépendante + du résumeur).