[🛠] Operations Automation #4: Une structure qui évite les états stale en modifiant moins de documents

✨ Résumé de GPT-5.6 Sol

Le récit de la réorganisation du flux de mise à jour documentaire : abandon de la copie de chaque changement d’état dans plusieurs documents, adoption d’un owner unique pour l’état volatil, de downstreams conditionnels et de checkpoints de phase.

Plus je mettais de documents à jour, plus l’état courant divergeait

Lorsqu’un long travail était compacté ou transféré à une autre session, il arrivait qu’une prochaine tâche inscrite dans un ancien document soit prise pour l’état courant. Pour éviter ce problème, j’ai pendant un temps corrigé tous les documents qui semblaient liés dès que l’état changeait.

Je répétais le même fait accompli et la prochaine tâche dans le README, le router documentaire, les exigences, la direction actuelle, le Runbook et le TODO. Tant qu’aucun document n’était oublié, cela semblait sûr.

Mais dès qu’un seul changement d’état était écrit à six endroits, il fallait maintenir ces six endroits parfaitement identiques. Un document restait à l’état antérieur au deploy, tandis qu’un autre indiquait que la vérification sur appareil réel était terminée. La multiplication des mises à jour documentaires, au lieu d’empêcher les états stale, en créait de nouveaux.

Chaque petite vérification terminée entraînait aussi la modification de plusieurs documents et la création d’un commit supplémentaire, ce qui fragmentait le Git history. Le nombre de synchronisations du texte devenait plus visible que la véritable fin de l’implémentation.

J’ai confié l’état volatil à un seul document

Le problème n’était pas le nombre de documents, mais le fait que plusieurs documents possédaient le même fait. J’ai donc commencé par désigner un owner unique pour chaque type de fait.

Fait modifié	owner	Condition pour modifier d’autres documents
Runtime actuel, blocker, phase et prochaine tâche	canonical current-state snapshot	Ne pas le copier dans d’autres documents
Décisions produit stables, contournements interdits et Goal actif	Document current-direction	Uniquement lorsque la décision produit elle-même ou le Goal change
Comportement, données, autorisations et acceptance	requirements ou contract	Uniquement lorsque le contrat de comportement de l’utilisateur ou du système change
Procédure opérationnelle, gate, rollback et recovery	Runbook	Uniquement lorsque la procédure que doit suivre l’opérateur change
Relations entre documents, étape du produit et point d’entrée d’exécution	README ou router	Uniquement lorsque le chemin de navigation ou la relation produit change
Commandes détaillées, logs et vérifications des workers	report, artifact et Git evidence	Ne conserver dans les documents aggregate que la conclusion et le lien vers la preuve

L’essentiel est de séparer être lié et être l'owner. La fin d’un deploy n’impose pas de modifier les exigences. Si la procédure opérationnelle de rollback a changé pendant le deploy, le Runbook est mis à jour ; si le contrat de comportement a lui aussi changé, les requirements le sont alors également.

Le README et le router ne suivent plus non plus la revision actuelle, l’état de l’appareil ni la prochaine tâche. Ces documents indiquent de façon stable seulement ce qu’il faut lire et où commencer l’exécution.

J’ai séparé la mise à jour immédiate du durable checkpoint

Un owner unique ne signifie pas que la mise à jour du document attend la fin de la phase. Lorsqu’une nouvelle preuve apparaît ou que l’état du Runtime, le blocker, la priorité ou la prochaine tâche change, le canonical current-state snapshot est corrigé avant l’implémentation suivante. Ainsi, même si le contexte est compacté ou transmis en cours de travail, la session suivante peut retrouver l’état réel à un seul endroit.

En revanche, aucun commit n’est créé à chaque changement d’une ligne d’état. Le current-state est vérifié une fois et un checkpoint n’est créé qu’à une frontière qui peut être relue et reprise indépendamment.

• lorsque l’implémentation est terminée
• lorsque le deploy et sa vérification a posteriori sont terminés
• lorsqu’un résultat E2E est obtenu sur un appareil réel ou au point d’entrée utilisateur, ou lorsqu’un blocker est confirmé
• lorsque le travail est transmis à la suite d’une interruption ou d’un handoff

La mise à jour immédiate sert à sécuriser le resume ; le phase checkpoint sert à relire et à annuler un ensemble de changements. Les traiter avec la même règle avait multiplié les micro-event commits.

Lorsque le travail ne dispose pas de l’autorisation de commit, la règle est encore plus simple. La fin de la review ne crée pas d’état COMMITTED ou CLOSED. Le candidat à l’intégration reste gelé et n’est pas présenté comme une conclusion durable avant l’existence d’un véritable checkpoint.

J’ai conservé les vérifications des workers dans les reports et les ai retirées des documents aggregate

Dans un travail parallèle, chaque worker produit des commandes exécutées, des résultats de vérification, des hunks qui se chevauchent et des contraintes restantes. Recopier tout cela dans le TODO racine, le README et les exigences ne fait qu’augmenter le nombre de documents que le coordinator doit lire.

Les preuves détaillées propres à chaque worker restent dans des reports immuables et dans le Git diff ; le current-state ne conserve que la conclusion intégrée, l’impact actuel et le chemin de la preuve. Le coordinator examine chaque report, mais ne traite pas un report comme un commit. Plusieurs reports appartenant à la même phase peuvent partager un seul checkpoint après la vérification intégrée.

Grâce à cette séparation, les documents aggregate sont plus courts sans que les vérifications détaillées disparaissent. La session suivante lit d’abord l’état actuel, puis ne descend vers les reports liés et le Git evidence que lorsqu’elle a besoin de comprendre le fondement d’une décision.

L’ordre de resume contredisait la règle d’owner

Après avoir réorganisé les règles, j’ai revu l’ensemble du flux et découvert une contradiction étonnamment élémentaire. La procédure de démarrage demandait de lire d’abord le README, puis le todo.md.

Le README disait de ne pas dupliquer l’état volatil, alors que la véritable procédure de resume lisait le router avant le current-state. S’il restait dans le router un ancien texte d’état, la toute première décision pouvait déjà partir dans la mauvaise direction.

J’ai donc changé l’ordre de démarrage. Le canonical current-state indique d’abord le Runtime actuel, le blocker, la phase et la prochaine tâche. Ensuite, le README et le router documentaire permettent de trouver les limites du repository et le document leaf nécessaire. Les décisions produit stables sont lues dans le current-direction, et le contrat de comportement réel dans les requirements.

Ajouter seulement une table des owners ne suffisait pas. L’ordre de lecture réel, qu’il s’agisse d’une personne ou d’un Agent, devait lui aussi suivre la relation de propriété.

Périmètre d’application actuel et limites restantes

Cette structure a été appliquée aux règles de travail partagées, au routing documentaire d’Operations Automation, au manifest de documentation des changements et au protocol de coordination parallèle. Le skill validator, la vérification de synchronisation documentaire et l’inspection du diff sont passés. Cependant, les changements se trouvent encore uniquement dans le local working tree et n’ont été ni commités ni deployed.

Je n’ai pas non plus réécrit rétroactivement l’ensemble des documents existants. L’historique et les reports détaillés ont été conservés ; ce n’est que lorsque le même fait de current-state entre en conflit entre des documents actifs qu’il est réduit à une référence vers l’owner. Avant de supprimer chaque ancien document, il importait surtout d’éviter qu’il soit de nouveau lu comme l’authority du travail actuel.

Désormais, la qualité de la mise à jour documentaire ne se mesure pas au nombre d’endroits modifiés. Le critère est de pouvoir lire un seul endroit après une compaction ou un handoff sans se tromper sur la phase actuelle ni sur la prochaine tâche, tout en pouvant retracer les preuves détaillées lorsqu’elles deviennent nécessaires.