De la mémoire technique au briefing de changement : faire expliquer une évolution sans inventer sa cause

Après mesurer, il fallait expliquer les changements

Le deep dive précédent portait sur une question assez simple à formuler : est-ce qu’une mémoire technique structurée aide réellement un agent à travailler sur un projet existant ? Les premiers résultats ont confirmé l’intérêt du contexte borné, de la provenance et de la validation humaine.

Mais une question restait ouverte : que peut-on dire lorsqu’un projet évolue ?

Un résumé de diff classique répond surtout à la question « quels fichiers ont changé ? ». Dans un workflow d’ingénierie, ce n’est pas toujours suffisant. Il faut pouvoir rattacher les changements à une Engineering Story, préciser la fenêtre observée et conserver la frontière entre ce que le dépôt établit et ce qu’il ne permet pas de conclure.

Le travail récent sur DevLog AI ajoute cette capacité sous la forme d’un briefing de changement. Le terme est volontairement modeste : il s’agit de décrire des éléments observés, pas de raconter une histoire plausible sur l’intention du développeur.

Le problème du résumé de diff

Un diff est une matière première, pas encore un contexte exploitable. Pris seul, il mélange souvent plusieurs niveaux :

  • les commits et les fichiers réellement présents dans une période ;

  • la story à laquelle on souhaite rattacher ces changements ;

  • les preuves déjà disponibles dans le contexte canonique ;

  • l’interprétation que l’on pourrait être tenté d’ajouter après coup.

Le dernier niveau est le plus dangereux. Une phrase comme « cette modification a été faite pour fiabiliser le calcul » peut sembler raisonnable, alors qu’elle n’est peut-être fondée que sur le nom d’une classe ou sur la forme du diff.

DevLog AI prend donc le parti inverse : le briefing doit être utile même lorsqu’il ne connaît pas la cause.

La fenêtre Git comme frontière

La première brique est la projection déterministe des changements. Elle travaille sur une fenêtre semi-ouverte :

(base, target]

Le commit de base est exclu, le commit cible est inclus. Cette convention évite une ambiguïté fréquente dans les résumés de comparaison : savoir si la borne de départ fait déjà partie de ce que l’on décrit.

La projection ne s’autorise pas à compléter silencieusement une fenêtre mal définie. Si les bornes sont absentes, invalides, inconnues, inatteignables ou si la parenté Git est incomplète, le système se ferme : il ne fabrique pas de changement technique à partir d’une hypothèse.

Les relations sont ensuite triées et plafonnées de manière déterministe. Il devient possible de rejouer la même requête avec le même contexte et d’obtenir un résultat comparable, ainsi qu’un avertissement explicite lorsqu’une limite s’applique.

De la question et du snapshot à la preuve Git puis au briefing descriptif

Un changement doit être une preuve typée

Le briefing ne transforme pas directement chaque ligne de diff en vérité métier. Il expose des changements comme des éléments de preuve du repository, avec une référence typée REPOSITORY_EVIDENCE.

Cette distinction paraît technique, mais elle change la manière de relire le résultat. Un lecteur peut demander :

  1. quelle story a servi de contexte ;

  2. quelles bornes Git ont été utilisées ;

  3. quel commit, fichier ou élément de diff soutient l’observation ;

  4. quel digest et quel snapshot d’audit correspondent à la projection ;

  5. quelles limites ont été rencontrées.

Le briefing est alors un point d’entrée vers les preuves, et non une couche qui les remplace.

Décrire sans conclure sur la cause

Le contrat de Story 0150 encode cette limite jusque dans le modèle de résultat. Le système peut décrire les changements autorisés, mais il ne conclut pas qu’ils ont été causés par une intention donnée.

Lorsque l’ancrage Git n’est pas établi, le statut groundingStatus reste NOT_ESTABLISHED et aucun changement technique n’est présenté comme établi. Lorsque le contexte est suffisamment ancré, le briefing reste descriptif : il peut dire qu’un service, un test ou une configuration a changé dans la fenêtre ; il ne peut pas affirmer pourquoi cette évolution a été faite sans preuve indépendante.

La phrase importante n’est donc pas seulement « voici les changements ». C’est aussi : « ce briefing ne conclut pas sur leur cause ni sur leur intention ».

Cette contrainte réduit l’effet de narration automatique. Elle rend le résultat moins spectaculaire, mais plus facile à auditer et plus sûr à transmettre à un agent ou à un autre développeur.

Un snapshot pour pouvoir relire le résultat

Un briefing est lié à un contexte canonique. Il conserve les éléments minimaux nécessaires pour comprendre dans quelles conditions il a été produit : identité du contexte, digest de projection, bornes observées et métadonnées d’audit.

L’objectif n’est pas de figer tout le repository dans chaque réponse. Il est de préserver une empreinte suffisante pour repérer qu’une réponse a été obtenue à partir d’un autre contexte, d’une autre fenêtre ou d’un autre état des preuves.

C’est une propriété importante pour un workflow assisté par IA. Une réponse textuelle peut rester la même alors que sa source a changé. Avec un snapshot et des références explicites, cette dérive devient visible au lieu d’être absorbée par la prose.

Une même capacité exposée par REST et MCP

Le briefing est disponible par l’API REST :

GET /api/v1/projects/{projectSlug}/stories/{storyId}/change-briefing

La description est optionnelle et le contrat réutilise la même projection Git que la brique de changements déterministes.

La capacité est aussi exposée côté MCP avec une ressource de la forme :

devlog://projects/{projectSlug}/stories/{storyId}/change-briefing

Ce partage est volontaire. L’interface utilisée par un humain et l’interface utilisée par un agent doivent parler de la même réalité, avec les mêmes bornes et les mêmes limites. Ajouter un canal d’accès ne doit pas créer une nouvelle autorité d’interprétation.

Ce que cela change dans le workflow

Un agent qui reprend une story ne reçoit plus seulement un contexte statique. Il peut obtenir une vue bornée de ce qui a évolué autour de cette story, puis décider avec un humain si ces éléments sont suffisants pour poursuivre.

Le flux devient lisible :

  1. une Engineering Story fournit le contexte de départ ;

  2. le Core construit ou retrouve le contexte canonique ;

  3. la projection Git sélectionne la fenêtre autorisée ;

  4. les changements sont convertis en preuves typées ;

  5. le briefing décrit ces preuves avec leur audit ;

  6. l’humain ou l’agent utilise ce briefing sans lui attribuer une intention qu’il ne contient pas.

Cette dernière étape est essentielle. Le briefing ne remplace ni une revue de code, ni une validation métier, ni une décision d’architecture. Il diminue le coût de reconstruction du contexte.

Ce que le système ne prétend pas savoir

Cette fonctionnalité ne répare pas un historique Git incomplet. Elle ne déduit pas une base manquante. Elle ne transforme pas un nom de commit en justification fiable. Elle ne prouve pas qu’une modification est correcte, ni qu’elle a atteint son objectif.

Elle ne donne pas non plus une nouvelle autorité au modèle d’IA. La résolution de la fenêtre, la sélection des preuves et les métadonnées de contexte restent contrôlées par le Core. L’IA peut ensuite aider à lire ou à formuler, mais elle ne doit pas combler un trou d’ancrage par une explication vraisemblable.

Les tests et les contrôles de qualité du travail récent couvrent les contrats principaux. Cela établit que l’implémentation et ses invariants sont vérifiés dans le repository ; cela ne constitue pas, à lui seul, une preuve de comportement sur tous les historiques ou toutes les intégrations de production.

En conclusion

La mémoire technique devient réellement utile lorsqu’elle sait aussi dire où s’arrête son observation.

Avec la projection déterministe des changements et le briefing ancré dans les preuves, DevLog AI peut maintenant relier une story à une fenêtre d’évolution concrète, exposer les changements sous une forme exploitable et conserver visibles ses limites.

Le résultat est moins proche d’un résumé automatique que d’un relevé d’audit lisible. C’est précisément l’objectif : aider à comprendre ce qui a bougé, sans inventer pourquoi.

État du travail

  • Implémenté : projection déterministe des changements et briefing descriptif d’une story ; références REPOSITORY_EVIDENCE ; exposition REST et MCP ; tests associés.

  • Décidé : fenêtre Git (base,target], comportement fail-closed et causalité non établie par défaut.

  • Limite : un historique incomplet ou des bornes non établies produisent un briefing non ancré, pas une reconstruction spéculative.

  • À vérifier avant généralisation : comportement sur les différents modes d’import Git et validation opérationnelle dans les environnements de déploiement.