La session est le message de commit

Un développeur hérite d’une base de code. git blame indique 47 fichiers modifiés en un seul commit. Le message indique : « refactor auth module ». L’auteur du commit est un développeur humain. L’auteur réel était un agent de codage qui a fonctionné pendant 90 minutes, lu 200 fichiers, évalué trois approches alternatives, rejeté deux d’entre elles pour des raisons précises, et produit un ensemble de modifications touchant chaque endpoint d’authentification. Les 90 minutes de décisions de conception, d’alternatives rejetées et de cas limites discutés ont disparu. Git a préservé ce qui a changé. Rien n’a préservé pourquoi.

Mon article sur la dette cognitive a nommé l’écart entre la vitesse de production des agents et la vitesse de compréhension des développeurs « dette cognitive » — un passif qui s’accumule à chaque commit non révisé.¹ Le projet Memento, qui a recueilli 100 points HN et 124 commentaires, pose la question suivante : si la session contient le raisonnement, la session devrait-elle faire partie du commit ?²

TL;DR

Git capture CE QUI a changé. Les sessions d’agents capturent POURQUOI. Quand les agents écrivent du code, la transcription de session est le véritable document de conception, et tout workflow qui supprime la transcription supprime la provenance. Memento (une extension git open source) attache les transcriptions de sessions IA aux commits sous forme de git notes, créant une chaîne de provenance du commit au raisonnement. L’intégration LSP de Claude Code ajoute une compréhension structurelle du code qui rend les transcriptions de session plus précises : go-to-definition remplace grep, et les signatures de type remplacent les suppositions. Ci-dessous : le fossé de provenance, quatre couches de métadonnées de session, ce que Memento construit, comment LSP change la qualité des données de session, et les pratiques minimales de provenance que vous pouvez mettre en œuvre dès aujourd’hui.

Le fossé de provenance

Git suit cinq éléments pour chaque modification : qui l’a faite, quand, quels fichiers ont changé, le diff, et un message de commit. Pour du code écrit par un humain, le message de commit comble le fossé entre le diff et l’intention. Un bon message explique pourquoi la modification existe. Un mauvais message (« fix stuff ») laisse le relecteur reconstruire l’intention à partir du code.

Le code écrit par un agent a une structure de provenance différente. L’intention ne réside pas dans la tête du développeur. L’intention réside dans la session : le prompt qui a lancé la tâche, les fichiers que l’agent a lus, les alternatives qu’il a évaluées, les outils qu’il a appelés, et les preuves qu’il a citées en rapportant l’achèvement. Un message de commit résumant 90 minutes de raisonnement d’agent en une ligne supprime 99,9 % du contexte décisionnel.

La perte n’est pas théorique. Mon système d’orchestration génère des fichiers d’état de session (jiro.state.json, jiro.progress.json) qui enregistrent chaque complétion d’histoire, verdict de relecteur, et résultat du portail de preuves.³ Quand un relecteur demande « pourquoi l’agent a-t-il utilisé le backoff exponentiel au lieu du circuit breaker ? », le fichier d’état de session contient la réponse : l’agent a évalué les deux patterns, constaté que le service en amont renvoie des 503 réessayables avec un en-tête Retry-After, et sélectionné le backoff exponentiel pour respecter la valeur de l’en-tête. Le message de commit dit « refactor: standardize retry patterns ». L’état de session dit pourquoi.

Sans provenance de session, la revue de code des modifications écrites par un agent devient de l’archéologie. Le relecteur lit le diff, reconstruit le raisonnement à rebours, et formule une théorie sur la raison d’être de la modification. La théorie peut être fausse. Le raisonnement réel de l’agent est disponible, enregistré dans la transcription de session. Le workflow standard de l’industrie (commit, push, relire le diff) jette le raisonnement.

Le problème se multiplie avec la composition d’agents. Mon système d’orchestration lance des sous-agents spécialisés pour la revue de code : un relecteur de correctness, un relecteur de sécurité, un relecteur de conventions.⁵ Chaque sous-agent exécute sa propre session, lit ses propres fichiers, forme ses propres conclusions. L’agent parent agrège les verdicts. Le message de commit final dit « 3 reviewers: approve ». Les trois sessions de revue individuelles — contenant chacune des constatations spécifiques, une analyse des cas limites, et la justification de l’approbation — vivent dans des transcriptions séparées que le commit ne référence jamais. Chaque couche de délégation d’agent ajoute une couche supplémentaire de raisonnement invisible.

Le problème de provenance se connecte à trois schémas de défaillance existants. Le pare-feu anti-fabrication a identifié comment les agents publient des affirmations non vérifiées quand aucun portail de sortie n’existe.⁶ La provenance de session aurait détecté la fabrication plus tôt : la transcription de session montrait l’agent inventant une méthodologie de comptage de tokens qu’aucun humain n’a révisée. L’agent invisible a documenté comment les actions des agents passent inaperçues sans instrumentation explicite.⁷ La provenance de session est la piste d’audit que la pile de visibilité génère. Le commentaire public au NIST recommandait une journalisation d’audit standardisée pour les actions des agents.⁹ Les git notes stockant les transcriptions de session sont une implémentation de cette recommandation.

Le portail de preuves de mon système qualité exige que l’agent cite une preuve spécifique pour chaque critère de qualité : nommer le pattern, expliquer les alternatives, lister les cas limites, coller la sortie des tests.¹⁰ Le portail de preuves force l’agent à générer des données des couches Raisonnement et Vérification qui n’existeraient pas autrement. Sans le portail, l’agent rapporte « terminé » et la session ne contient que des données de Processus (appels d’outils). Avec le portail, la session contient une justification explicite qu’un relecteur peut vérifier par rapport au code.

Git seul ne peut pas distinguer entre un commit de 47 fichiers représentant 90 minutes de raisonnement minutieux et un commit de 47 fichiers représentant un agent fonctionnant sans contrainte pendant 90 minutes sans revue. La documentation de git décrit les notes comme « des informations supplémentaires sur un objet qui peuvent être attachées sans modifier l’objet lui-même ».⁸ Les transcriptions de session correspondent exactement à cette définition : des informations supplémentaires sur la provenance d’un commit qui n’altèrent ni le hash du commit, ni le diff, ni l’historique.

La question Memento

Le projet Memento répond au fossé de provenance avec une extension git.² L’outil capture les transcriptions de sessions de codage IA et les attache aux commits sous forme de git notes, stockées dans refs/notes/commits et refs/notes/memento-full-audit.

Le workflow : git memento init configure le dépôt. git memento commit <session-id> remplace git commit, en récupérant automatiquement la transcription de session auprès du fournisseur IA configuré (Codex ou Claude Code) et en la stockant comme métadonnées structurées sur le commit.

La discussion de 124 commentaires sur HN a fait émerger quatre positions :

Position 1 : les sessions sont un contexte essentiel. Les sessions d’agents contiennent le raisonnement que les messages de commit ne peuvent pas exprimer. Attacher les sessions aux commits préserve la chaîne de provenance. Les relecteurs peuvent retracer n’importe quelle ligne de code à travers le commit, la session et le prompt original.

Position 2 : les sessions sont du bruit. Une transcription de session de 90 minutes représente des milliers de lignes de conversation. La plupart sont sans rapport avec l’ensemble final de modifications. Attacher la transcription complète noie le signal dans le bruit et rend la revue plus difficile, pas plus facile.

Position 3 : des résumés, pas des transcriptions. La session devrait être distillée en un résumé structuré : description de la tâche, alternatives envisagées, justification de la décision, preuves citées. Le résumé préserve la provenance sans le bruit. Memento génère des résumés en markdown étiquetés avec les tours utilisateur et assistant.

Position 4 : préoccupations de confidentialité et de sécurité. Les transcriptions de session peuvent contenir des clés API, des URL internes, du code propriétaire d’autres fichiers, ou du contenu conversationnel que le développeur ne voudrait pas dans un enregistrement git permanent. Les sessions nécessitent une sanitisation avant l’attachement.

Les quatre positions ont du mérite. La valeur de provenance des sessions est indéniable. Le problème du bruit est réel. La préoccupation de confidentialité est structurelle. Memento traite les positions 1 et 3 (stockage de transcriptions avec conversion markdown) et la position 4 (traitement des transcriptions comme données non fiables pour la génération de résumés). La position 2 reste une question de conception ouverte : combien de contexte de session suffit ?

Un outil complémentaire adopte une approche différente du même problème. claude-replay convertit les transcriptions de sessions Claude Code en lecture de type vidéo, permettant aux relecteurs de regarder le travail de l’agent se dérouler étape par étape plutôt que de lire une transcription statique.¹² Là où Memento répond à « que devrions-nous stocker ? », claude-replay répond à « comment devrions-nous le relire ? » Les deux outils traitent des parties différentes du workflow de provenance : Memento préserve les données (stockage), claude-replay rend les données compréhensibles (présentation). Le fait que les deux projets aient émergé indépendamment au cours du même mois valide la thèse : les praticiens ressentent le fossé de provenance et construisent des outils pour le combler.

Quatre couches de provenance

Les métadonnées de session d’agent s’organisent en quatre couches, chacune répondant à une question différente sur la modification.

Chaque couche a un coût. Stocker la couche Intention complète (prompt original) est peu coûteux : un champ texte. Stocker la couche Processus complète (chaque appel d’outil) pour une session de 90 minutes génère des mégaoctets de JSON. Stocker la couche Raisonnement exige que l’agent narre explicitement son processus décisionnel, ce que la plupart des agents ne font pas par défaut. Stocker la couche Vérification nécessite une intégration avec le lanceur de tests et le système de revue.

Mon système d’orchestration capture les quatre couches à travers différents mécanismes.³ L’infrastructure de hooks qui rend cette capture possible s’étend sur 84 hooks répartis sur 15 types d’événements.⁵ Intention : le hook UserPromptSubmit enregistre le prompt original. Processus : les hooks PostToolUse enregistrent chaque appel d’outil et son résultat. Raisonnement : le portail de preuves exige que l’agent cite une justification spécifique pour chaque critère de qualité. Vérification : le fichier jiro.state.json enregistre les sorties de tests et les verdicts des relecteurs.

Les hooks suivent également quels skills l’agent a invoqués et dans quel ordre.¹¹ Un commit résultant du skill /review suivi du skill /test a un profil de provenance différent d’un commit issu d’une session unique non structurée. La séquence des skills révèle le pattern du workflow : revue avant les tests, ou tests avant la revue ? L’ordre est important pour comprendre la couverture d’assurance qualité. Les données existent dans plusieurs fichiers d’état. Le problème est qu’aucune d’entre elles ne s’attache au commit git.

LSP comme pont de provenance

L’intégration LSP (Language Server Protocol) de Claude Code change la qualité des données de provenance de session.⁴

Avant LSP, Claude Code naviguait dans les bases de code par grep et lectures de fichiers. Quand l’agent devait trouver la définition d’une fonction, il cherchait le nom de la fonction dans tous les fichiers. La recherche renvoyait des résultats flous : correspondances multiples, correspondances partielles, fichiers de test contenant le nom de la fonction dans des commentaires. L’agent sélectionnait la correspondance la plus probable. La transcription de session enregistrait : « recherché authenticate_user, trouvé dans auth.py, test_auth.py et middleware.py ». Les données de provenance contiennent la recherche, l’ambiguïté, et la meilleure estimation de l’agent.

Avec LSP, l’agent appelle goToDefinition et reçoit le fichier exact et le numéro de ligne en ~50 millisecondes.⁴ La transcription de session enregistre : « authenticate_user défini à auth.py:47 ». Les données de provenance sont précises, non ambiguës et vérifiables par machine. Un relecteur lisant la session peut avoir confiance que l’agent a trouvé la bonne définition, et non une fonction au nom similaire dans un module différent.

L’amélioration se compose au fil de la session. Un agent qui lit 200 fichiers via grep génère des données de session pleines de « recherché X, correspondances potentielles trouvées A, B, C, sélectionné A ». Un agent qui lit 200 fichiers via LSP génère des données de session qui disent « X défini à fichier:ligne, références à fichier:ligne, fichier:ligne, fichier:ligne ». La session reposant sur LSP est une carte précise de la compréhension du code par l’agent. La session reposant sur grep est une approximation floue.

LSP ajoute six capacités qui améliorent la qualité de la provenance :

L’implication pour la provenance : les transcriptions de session des agents activés par LSP ont plus de valeur en tant que documents de conception parce que chaque étape de navigation dans le code est vérifiable. Un relecteur peut confirmer que la compréhension du code par l’agent était correcte, et pas seulement plausible.

Le projet code-review-graph pousse la compréhension structurelle plus loin : un graphe de code persistant qui survit d’une session à l’autre, réduisant le coût en tokens de la re-compréhension de la base de code à chaque invocation.¹³ Là où LSP fournit des requêtes structurelles au sein d’une session, un graphe persistant fournit une mémoire structurelle entre les sessions. Pour la provenance, l’implication est que les futurs agents transporteront non seulement la transcription de session mais aussi la compréhension structurelle qui a produit les décisions. Le graphe devient une couche supplémentaire de données de provenance : non seulement « l’agent a trouvé authenticate_user à auth.py:47 » mais « le graphe de code de l’agent contenait déjà la hiérarchie d’appels, donc il a sauté la navigation et est allé directement à l’implémentation ». La connaissance préalable de l’agent influence ses décisions, et cette connaissance préalable appartient à la chaîne de provenance.

À quoi ressemblent les métadonnées de session

Un exemple réel tiré de mon système d’orchestration. Histoire : « Ajouter une limitation de débit à l’endpoint d’authentification. »

Couche Intention (depuis le hook UserPromptSubmit) :

Prompt: "Implement rate limiting on POST /auth/login.
  Use sliding window, 5 attempts per minute per IP.
  Return 429 with Retry-After header."

Couche Processus (depuis les hooks PostToolUse) :

Files read: 14 (auth/, middleware/, tests/)
Files written: 3 (rate_limiter.py, auth.py, test_rate_limit.py)
Bash commands: 7 (pytest x3, pip install x1, curl x3)
Duration: 23 minutes
Token usage: 87K input, 24K output

Couche Raisonnement (depuis le portail de preuves) :

Pattern: Sliding window (token bucket rejected
  because per-IP granularity requires separate
  counters, sliding window handles this natively)
Edge cases: IPv6 normalization, proxy headers
  (X-Forwarded-For validated against trusted proxy list)

Couche Vérification (depuis jiro.state.json) :

Tests: 12 passed, 0 failed, 0 skipped
Reviewers: correctness (approve), security (approve),
  conventions (approve with note: add docstring to
  rate_limiter.py:RateLimiter class)
Evidence gate: 6/6 criteria met

Le message de commit pour la même modification : « feat: add rate limiting to auth endpoint ». Quatorze mots. Les métadonnées de session contiennent 2 300 mots de provenance structurée. L’écart entre le message de commit et le contexte de session est de deux ordres de grandeur.

Le coût de la provenance

La provenance de session n’est pas gratuite. Trois coûts contraignent l’adoption.

Stockage. Une session d’agent de 90 minutes génère 500 Ko à 2 Mo de transcription brute. À 10 commits par jour, la transcription complète ajoute 5 à 20 Mo quotidiennement au dépôt git. Les git notes stockent les données en dehors de l’historique principal (elles n’affectent pas la taille du git clone par défaut), mais la piste d’audit dans refs/notes/memento-full-audit s’accumule. La conversion markdown de Memento réduit la taille brute d’environ 60 %.²

Confidentialité. Les transcriptions de session contiennent tout ce que l’agent a vu : contenus de fichiers, variables d’environnement, réponses API, messages d’erreur avec traces de pile. Une transcription attachée à un dépôt public expose des détails d’implémentation internes. Memento traite les transcriptions comme des données non fiables et ordonne au modèle de résumé d’ignorer les instructions embarquées, mais la transcription brute dans la piste d’audit complète nécessite un contrôle d’accès.²

Rapport signal/bruit. Une session de 90 minutes où l’agent lit 200 fichiers pour en modifier 12 contient 188 fichiers de données de processus non pertinentes. Le défi est de distinguer la navigation (bruit) des points de décision (signal). Le modèle à quatre couches aide : Intention et Raisonnement sont à signal élevé, Processus est mixte, Vérification est à signal élevé. Un système de provenance qui stocke Intention et Raisonnement par défaut et le Processus à la demande réduit le bruit sans perdre le contexte décisionnel critique.

Ce que vous pouvez mettre en œuvre dès aujourd’hui

Quatre pratiques minimales de provenance qui ne nécessitent aucun nouvel outil :

1. Messages de commit structurés. Remplacez « refactor auth module » par un format structuré :

feat: add rate limiting to auth endpoint

Task: sliding window rate limiter, 5/min per IP
Alternatives: token bucket (rejected: per-IP overhead)
Evidence: 12 tests pass, 3 reviewers approve
Session: 23 min, 87K tokens, 14 files read

Le format est une version manuelle des quatre couches de provenance. Le message répond à l’intention (tâche), au raisonnement (alternatives) et à la vérification (preuves) en quatre lignes. Aucun outillage requis.

2. Sauvegardez les transcriptions de session à côté des commits. Après une session d’agent, exportez la transcription dans un fichier du dépôt (par ex., .sessions/2026-03-02-auth-rate-limit.md). Ajoutez le fichier au .gitignore pour les dépôts publics ou committez-le pour les dépôts internes. La transcription est disponible pour la revue sans infrastructure de git notes.

3. Étiquetez les commits écrits par des agents. Utilisez un trailer git pour marquer les commits produits par un agent :

Agent: Claude Code (Opus)
Session-Duration: 23m
Files-Read: 14
Files-Written: 3

Le trailer crée un enregistrement analysable par machine de l’implication de l’agent. git log --grep="Agent: Claude Code" liste tous les commits écrits par l’agent. Les métadonnées permettent aux futurs outils de reconstruire les chaînes de provenance sans annotation rétroactive.

4. Exigez des portails de preuves pour les commits d’agents. Avant qu’un agent ne committe, exigez qu’il réponde à six questions : quel pattern le code suit-il ? Quelles alternatives plus simples existent ? Quels cas limites sont gérés ? Les tests passent-ils ? Quels fichiers avez-vous vérifiés pour les régressions ? La modification résout-elle le problème réel ?¹⁰ Les réponses forment les couches Raisonnement et Vérification. Sans le portail, l’agent rapporte « terminé » et la session ne contient que des données de Processus. Avec le portail, chaque commit génère de la provenance structurée comme effet secondaire de l’assurance qualité.

La pratique du portail de preuves se connecte à l’argument plus large de la provenance. Un agent qui doit justifier ses décisions avant de committer génère des métadonnées de session de meilleure qualité qu’un agent fonctionnant sans contrainte. Le portail transforme la provenance d’un sous-produit passif (enregistrer ce qui s’est passé) en un signal de qualité actif (exiger que l’agent explique ce qui s’est passé et pourquoi).

Points clés à retenir

Pour les responsables d’ingénierie : chaque commit écrit par un agent avec un message d’une ligne supprime le document de conception. La transcription de session contient le raisonnement. Décidez si ce raisonnement a de la valeur pour les workflows de revue de code, d’intégration et de réponse aux incidents de votre équipe. Si la réponse est oui, mettez en place des messages de commit structurés au minimum.

Pour les développeurs : quand vous héritez de code écrit par un agent, le message de commit vous dit ce qui a changé. La transcription de session (si elle est préservée) vous dit pourquoi. Plaidez pour la provenance de session dans le workflow d’agents de votre équipe. Le projet Memento fournit une approche native git. Les messages de commit structurés offrent un point de départ sans infrastructure.

Pour les créateurs d’outils : l’intégration LSP rend les transcriptions de session plus précieuses en remplaçant la navigation floue basée sur grep par des références de code précises et vérifiables. Chaque amélioration de la compréhension du code par l’agent améliore la qualité des données de provenance que les sessions génèrent. Construisez des formats d’export qui préservent les quatre couches de provenance.

FAQ

Qu’est-ce que la provenance de session ? La provenance de session est l’enregistrement du processus de raisonnement d’un agent IA durant une session de codage : la tâche originale, les fichiers lus, les alternatives évaluées, les décisions prises et les preuves produites. La transcription de session capture le « pourquoi » que les messages de commit et les diffs ne peuvent pas exprimer.

Qu’est-ce que Memento ? Memento est une extension git open source qui capture les transcriptions de sessions de codage IA et les attache aux commits sous forme de git notes. L’outil prend en charge Codex et Claude Code, génère des résumés en markdown, et fournit une GitHub Action pour l’intégration aux PR.²

Comment LSP améliore-t-il les sessions d’agents ? Le Language Server Protocol donne aux agents une compréhension structurelle du code : définitions exactes, références typées, hiérarchies d’appels et diagnostics en temps réel. Les transcriptions de session des agents activés par LSP contiennent des données de navigation de code précises et vérifiables au lieu de résultats grep flous.⁴

Les transcriptions de session devraient-elles être committées dans git ? La réponse dépend des exigences de confidentialité du dépôt. Pour les dépôts internes, committer les transcriptions préserve la provenance. Pour les dépôts publics, les git notes (qui ne sont pas transférées par défaut lors d’un clone) ou un stockage séparé avec des références de commit sont des approches plus sûres.²

Quel volume de stockage la provenance de session nécessite-t-elle ? Une session d’agent typique de 30 minutes génère 200 Ko à 800 Ko de transcription brute. Les git notes stockent les données en dehors de la base d’objets principale, laissant la taille du git clone inchangée par défaut. La conversion markdown de Memento réduit la taille brute d’environ 60 %. Pour les équipes exécutant 10 à 20 sessions d’agents par jour, prévoyez 2 à 10 Mo de données de provenance quotidiennes, comparable à une capture d’écran en résolution moyenne par session.²

Quelle est la relation entre l’observabilité des agents et la provenance de session ? L’observabilité des agents surveille ce que font les agents en temps réel : consommation de ressources, conformité aux politiques, comportement à l’exécution.⁷ La provenance de session enregistre ce que les agents ont décidé et pourquoi, après coup. L’observabilité répond à « l’agent se comporte-t-il correctement en ce moment ? » La provenance répond à « pourquoi l’agent a-t-il fait ce choix mardi dernier ? » Les deux systèmes se complètent : l’observabilité détecte les problèmes en direct, la provenance les explique après coup.

Sources