La session est le message de commit

Un développeur hérite d’une base de code. git blame montre 47 fichiers modifiés dans un seul commit. Le message indique : « refactor auth module ». L’auteur du commit est listé comme un développeur humain. L’auteur réel était un agent de programmation 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 point d’accès 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 ?²

En bref

Git capture CE QUI a changé. Les sessions d’agents capturent POURQUOI. Quand les agents écrivent du code, la transcription de session est le vrai document de conception, et tout flux de travail 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. La nouvelle 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 produit 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 seule 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 achèvement de story, verdict de relecteur et résultat de porte de preuves.³ Quand un relecteur demande « pourquoi l’agent a-t-il utilisé un backoff exponentiel au lieu d’un 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 produites par un agent devient de l’archéologie. Le relecteur lit le diff, reconstitue le raisonnement par ingénierie inverse, et élabore 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 flux de travail 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 correction, 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 — chacune contenant 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 patterns de défaillance existants. Le pare-feu de fabrication a identifié comment les agents publient des affirmations non vérifiées quand aucune porte 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’avait 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 a recommandé 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.

La porte de preuves de mon système qualité exige que l’agent cite des preuves spécifiques pour chaque critère de qualité : nommer le pattern, expliquer les alternatives, lister les cas limites, coller la sortie des tests.¹⁰ La porte de preuves force l’agent à générer des données des couches Raisonnement et Vérification qui n’existeraient pas autrement. Sans la porte, l’agent rapporte « terminé » et la session ne contient que des données de Processus (appels d’outils). Avec la porte, 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 qui représente 90 minutes de raisonnement soigneux et un commit de 47 fichiers qui représente un agent fonctionnant sans contrainte pendant 90 minutes sans revue. La documentation 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 programmation IA et les attache aux commits sous forme de git notes, stockées dans refs/notes/commits et refs/notes/memento-full-audit.

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

La discussion HN de 124 commentaires 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 capturer. Attacher les sessions aux commits préserve la chaîne de provenance. Les relecteurs peuvent remonter 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 majeure partie est 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 considérées, justification des décisions, 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 de l’utilisateur et de l’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 provenant d’autres fichiers, ou du contenu conversationnel que le développeur ne voudrait pas dans un enregistrement Git permanent. Les sessions nécessitent un assainissement 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 adresse les positions 1 et 3 (stockage de transcription 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 est suffisant ?

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 ajoute 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 de décision, 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 la capture possible couvre 84 hooks répartis sur 15 types d’événements.⁵ Intention : le hook UserPromptSubmit journalise le prompt original. Processus : les hooks PostToolUse journalisent chaque appel d’outil et son résultat. Raisonnement : la porte 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 la sortie des 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 seule session non structurée. La séquence de skills révèle le pattern de flux de travail : revue avant les tests, ou tests avant la revue ? L’ordre compte 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

La nouvelle 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 via grep et la lecture de fichiers. Quand l’agent devait trouver la définition d’une fonction, il recherchait le nom de la fonction dans tous les fichiers. La recherche retournait 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 : « recherche de 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, pas 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 « recherche de X, correspondances potentielles A, B, C, sélection de 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 appuyée par LSP est une carte précise de la compréhension du code par l’agent. La session appuyée par 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 équipés de LSP sont plus précieuses 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 de la base de code par l’agent était correcte, pas seulement plausible.

À quoi ressemblent les métadonnées de session

Un exemple réel de mon système d’orchestration. Story : « Ajouter une limitation de débit au point d’accès 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 la porte 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 de 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 : contenu des 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 instruit le modèle de résumé d’ignorer les instructions intégrées, mais la transcription brute dans la piste d’audit complète nécessite un contrôle d’accès.²

Ratio 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 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 aux côtés des commits. Après une session d’agent, exportez la transcription vers un fichier dans le 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 produits par les 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 produits par un agent. Les métadonnées permettent à l’outillage futur de reconstruire les chaînes de provenance sans annotation rétroactive.

4. Exigez des portes 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 la porte, l’agent rapporte « terminé » et la session ne contient que des données de Processus. Avec la porte, chaque commit génère de la provenance structurée comme effet secondaire de l’assurance qualité.

La pratique de la porte 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 qui fonctionne sans contrainte. La porte transforme la provenance d’un sous-produit passif (enregistrer ce qui s’est passé) en un signal actif de qualité (exiger que l’agent explique ce qui s’est passé et pourquoi).

Points clés

Pour les responsables techniques : Chaque commit produit par un agent avec un message d’une ligne supprime le document de conception. La transcription de session contient le raisonnement. Déterminez si ce raisonnement a de la valeur pour les flux de travail 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 produit 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 flux de travail d’agents de votre équipe. Le projet Memento offre 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 les agents 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 pendant une session de programmation : 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 capturer.

Qu’est-ce que Memento ? Memento est une extension Git open source qui capture les transcriptions de sessions de programmation 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 des 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 équipés de 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 doivent-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 du clonage) ou un stockage séparé avec des références de commit sont des approches plus sûres.²

Combien 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, maintenant les tailles de git clone inchangées 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, comparables à 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 les agents font 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