Précision du suivi et validation

La session 079 devait être un rapide nettoyage : compléter deux tests manquants pour TEMP-2 (Accès temporel) et passer à la suite. Au lieu de cela, elle est devenue une leçon sur l'écart entre ce que dit la documentation et ce que fait le code -- et une étude de cas sur pourquoi la validation compte plus que l'estimation.

La session a commencé avec le modèle temporel suivi à cinquante et un virgule neuf pour cent. Elle s'est terminée à cinquante-sept virgule cinq pour cent. Non pas parce que nous avons écrit beaucoup de nouveau code, mais parce que nous avons découvert que neuf tâches étaient déjà complètes et n'avaient jamais été enregistrées.

Le déclencheur de l'audit

Le document de suivi listait TEMP-2 (Accès temporel) à quatre-vingt-neuf pour cent -- seize sur dix-huit tâches. Deux tâches restaient :

• TEMP2-17 : Tester l'accès relatif (user @ -1, user @ -2)
• TEMP2-18 : Tester l'accès temporel absolu (user @ "2024-01-15")

Le plan était simple : écrire deux tests d'intégration, marquer les tâches comme complètes, passer à la suite. Cinq minutes de travail, peut-être dix.

Mais quand nous avons ouvert tests/temporal_integration.rs pour ajouter les tests, nous les avons trouvés déjà là. Sept tests d'intégration complets couvrant exactement la fonctionnalité que le document de suivi prétendait non testée :

test_temporal_relative_minus_1          -- accès @ -1
test_temporal_relative_minus_2          -- accès @ -2
test_temporal_relative_out_of_range     -- gestion hors limites
test_temporal_relative_zero_is_current  -- @ 0 retourne la version actuelle
test_temporal_relative_access_field_directly  -- accès direct aux champs du résultat
test_temporal_absolute_date_no_match    -- chaîne de date sans correspondance
test_temporal_absolute_datetime_no_match -- DateTime sans correspondance

Tous les sept passaient. TEMP-2 était déjà à cent pour cent. Il était à cent pour cent depuis la session 076. Le document de suivi n'avait simplement pas été mis à jour.

La découverte en cascade

Trouver TEMP-2 déjà complet a déclenché une investigation plus approfondie. Si ces tâches étaient mal étiquetées comme incomplètes, quoi d'autre était erroné ?

TEMP-3 (Mots-clés temporels) était listé à soixante-dix-neuf pour cent -- onze sur quatorze tâches. Trois tâches étaient supposément manquantes. Mais l'implémentation était pleinement fonctionnelle : les sept mots-clés étaient lexés, parsés, vérifiés, compilés et exécutés correctement. Les tâches « manquantes » étaient des tests, et nous avons écrit deux fichiers de test pour combler le fossé :

flin// temporal-keywords-test.flin -- Teste les 7 mots-clés
user = User { name: "Test" }
save user

// Vérifier que tous les mots-clés produisent des horodatages valides
current = now
today_start = today
yesterday_start = yesterday

// Vérifier les relations
<div>
{if current > yesterday_start}
    <p>Maintenant est après hier : correct</p>
{/if}
{if today_start > yesterday_start}
    <p>Aujourd'hui est après hier : correct</p>
{/if}
</div>

flin// temporal-keyword-comparisons-test.flin -- Mots-clés dans les conditions
entity Event {
    name: text
    scheduled_at: time
}

event = Event { name: "Réunion", scheduled_at: now + 7.days }
save event

// Mots-clés dans les comparaisons
<div>
{if event.scheduled_at > now}
    <p>L'événement est dans le futur</p>
{/if}
{if event.scheduled_at > yesterday}
    <p>L'événement est après hier</p>
{/if}
</div>

Les deux fichiers de test ont passé la vérification syntaxique et l'exécution. TEMP-3 est passé à cent pour cent.

TEMP-8 (Suppression/Restauration définitive) était listé à huit pour cent -- une sur douze tâches. Mais la session 077 avait implémenté le cycle complet destroy/restore :

• Mot-clé destroy : entièrement implémenté (lexer, parseur, vérificateur de types, codegen, VM).
• Fonction restore() : entièrement implémentée (built-in de la VM, enregistrement dans le vérificateur de types).
• Méthodes de base de données : destroy() et restore() fonctionnant dans ZeroCore.
• Tests d'intégration : neuf tests destroy/restore passant.

Cinq tâches fondamentales étaient déjà complètes. TEMP-8 est passé de huit pour cent à quarante-deux pour cent.

Les chiffres

L'audit de suivi a révélé :

Six tâches ont été découvertes comme déjà complètes. Trois tâches ont été nouvellement complétées en écrivant des fichiers de test. Le résultat net a été un bond de cinq virgule six pour cent de progression à partir d'une session qui devait être un simple nettoyage.

Pourquoi la documentation a dérivé

La cause profonde était un trou dans le flux de travail. Les sessions d'implémentation se concentraient sur l'écriture de code et le passage des tests. Les mises à jour du suivi se faisaient à la fin des sessions, si elles se faisaient. Quand la session 076 a atteint cent pour cent de couverture de tests temporels, les tests pour TEMP-2 étaient parmi ceux qui passaient -- mais le document de suivi a été mis à jour avec le nombre global de tests, pas avec la granularité au niveau des tâches.

La session 077 a implémenté destroy et restore avec neuf tests d'intégration. Le journal de session documentait tout. Mais le fichier de suivi global n'a été que partiellement mis à jour car la session s'est terminée tard et la priorité était de committer du code fonctionnel, pas de la comptabilité administrative.

C'est un pattern universel dans les projets logiciels : l'implémentation dépasse la documentation. Le code est la source de vérité, mais le document de suivi est ce que les gens lisent. Quand ils divergent, les décisions sont prises sur la base d'informations obsolètes.

Leçons pour le suivi de projet

1. Toujours vérifier avant d'implémenter

Si nous avions commencé à écrire les tests TEMP-2 sans vérifier s'ils existaient, nous aurions créé des tests en double. Pire, nous aurions pu introduire des différences subtiles entre les doublons, créant une confusion de maintenance.

La règle désormais : avant de marquer une tâche comme « à faire », chercher dans le code les implémentations existantes. Exécuter les tests existants. Vérifier que le fossé est réel.

2. Le code est la source de vérité

Le document de suivi disait trois pour cent. Le code disait trente-sept virgule cinq pour cent. Le document de suivi disait quatre-vingt-neuf pour cent pour TEMP-2. Le code disait cent pour cent. Dans chaque cas, le code avait raison et le document avait tort.

Pour une équipe de deux personnes (un humain, une IA), cela signifie que le moyen le plus fiable d'évaluer la progression est de lire le code et d'exécuter les tests -- pas de lire le fichier de suivi. Le fichier de suivi est un outil de planification, pas un outil d'audit.

3. La couverture de tests est la vraie métrique

Le document de suivi suivait des « tâches » -- un mélange de travail d'implémentation, de couverture de tests et de documentation. Mais les seules tâches qui comptaient pour « cette fonctionnalité est-elle terminée ? » étaient les tests. Si une fonctionnalité a des tests complets qui passent, elle fonctionne. Si elle n'a pas de tests, elle fonctionne peut-être -- mais vous ne pouvez pas le prouver.

La session 079 a renforcé ce que la session 068 avait déjà montré : le modèle temporel avait bien plus de code fonctionnel que quiconque ne le réalisait, mais sans tests d'intégration, « fonctionnel » était une supposition, pas un fait.

4. Les petites sessions ont un impact disproportionné

La session 079 n'était pas une session marathon d'implémentation. Aucune nouvelle architecture n'a été conçue. Aucun algorithme complexe n'a été implémenté. La session a audité le travail existant, écrit deux fichiers de test et mis à jour la documentation de suivi.

L'impact : neuf tâches complétées, deux catégories à cent pour cent, et un bond de cinq virgule six pour cent de progression globale. Le meilleur retour sur investissement en temps de toutes les sessions du modèle temporel.

Patterns de validation pour les données temporelles

Au-delà du suivi de projet, la session 079 a fait émerger plusieurs patterns de validation pour les données temporelles elles-mêmes -- des cas limites que les tests ont confirmé fonctionner correctement.

Accès temporel hors limites

Que se passe-t-il quand vous demandez une version qui n'existe pas ?

flinuser @ -100    // Seulement 3 versions existent

La VM gère cela avec élégance : elle retourne None. Pas de crash, pas d'exception. Le développeur gère le cas d'absence via le système de types optionnels de FLIN.

Cela a été validé sans écrire de nouveau code -- le test existant test_temporal_relative_out_of_range le couvrait. La recherche dans l'historique de la VM échoue simplement à trouver une version correspondante et retourne None au lieu d'indexer hors limites.

Cohérence de l'ordonnancement des mots-clés

Les mots-clés temporels sont-ils correctement ordonnés ? now est-il toujours supérieur à yesterday ? today est-il toujours supérieur à last_week ?

flin// Ceux-ci devraient toujours être vrais
now > yesterday         // true
today > yesterday       // true
now > last_week         // true
now > last_month        // true
last_week > last_month  // true

Le fichier de test des mots-clés a validé huit relations de ce type. Toutes étaient vérifiées. Les calculs d'horodatage utilisent UTC, ce qui élimine les incohérences d'ordonnancement liées aux fuseaux horaires.

Mots-clés dans les expressions conditionnelles

Les mots-clés temporels doivent fonctionner non seulement comme opérandes de @ mais aussi comme valeurs dans les expressions générales :

flinentity Event {
    name: text
    scheduled_at: time
}

event = Event { name: "Réunion", scheduled_at: now + 7.days }
save event

// Mots-clés dans les expressions booléennes
is_future = event.scheduled_at > now
is_recent = event.scheduled_at > last_week

Le fichier de test de comparaison a vérifié que les mots-clés s'évaluent correctement dans les blocs {if}, dans les affectations de variables et dans les comparaisons de champs d'entités. Tout passait.

Interaction entre suppression douce et accès temporel

Une entité supprimée en douceur ne devrait pas apparaître dans les requêtes standard mais devrait toujours être accessible via l'accès temporel :

flinuser = User { name: "Test" }
save user
delete user

// Requête standard : non trouvé
found = User.find(user.id)           // none

// Accès temporel : historique préservé
old = user @ -1                      // La version précédente existe

Cette interaction était déjà testée mais n'avait pas été explicitement suivie comme cas de validation. La session 079 a confirmé qu'elle fonctionnait correctement.

L'état après la session 079

Cinq catégories à cent pour cent :

Global : quatre-vingt-douze sur cent soixante tâches (cinquante-sept virgule cinq pour cent).

Tous les mille quarante-six tests passant (tests de bibliothèque plus tests d'intégration). Zéro régression.

Le pattern plus large : la dette de documentation

La session 079 a exposé une forme de dette technique qui reçoit moins d'attention que la dette de code : la dette de documentation. Quand la documentation prend du retard sur l'implémentation, les conséquences se répercutent en cascade :

Erreurs de planification. Si le document de suivi dit qu'une fonctionnalité n'est pas implémentée, quelqu'un pourrait planifier une session pour l'implémenter -- gaspillant du temps sur un travail déjà fait. C'est ce qui s'est passé avec TEMP-2 : nous avons alloué du temps pour écrire des tests qui existaient déjà.

Échecs de communication. Quand Thales a demandé « où en est le modèle temporel ? », la réponse basée sur la documentation était cinquante-deux pour cent. La réponse basée sur le code était cinquante-huit pour cent. Pour un CEO prenant des décisions produit, cet écart de six pour cent pourrait changer les priorités.

Impact sur le moral. Travailler sur une fonctionnalité qui est « à cinquante-deux pour cent » se ressent différemment que travailler sur une fonctionnalité à « cinquante-huit pour cent ». La perception de la progression affecte la motivation, et une documentation obsolète sous-rapporte systématiquement la progression, donnant à l'équipe l'impression d'être en retard alors qu'elle est en réalité en avance.

Risque de travail en double. La conséquence la plus coûteuse. Si un développeur (humain ou IA) implémente une fonctionnalité sans vérifier si elle existe, le résultat est du code dupliqué, des implémentations conflictuelles et des bugs d'intégration.

La solution n'est pas de « meilleures pratiques de documentation » -- c'est le même conseil que chaque projet ignore. La solution est de faire de la vérification une habitude. Avant chaque session touchant aux fonctionnalités temporelles, nous exécutons maintenant la suite de tests d'intégration et vérifions le nombre de tests. Le nombre de tests ne ment pas. Si trente-six tests passent, trente-six fonctionnalités marchent. Aucun document nécessaire.

Appliquer cela au flux de travail CEO-IA CTO

Le problème de précision du suivi est amplifié dans le flux de travail CEO-IA CTO en raison du fonctionnement des sessions. Chaque session est relativement indépendante -- Claude reçoit du contexte sur ce qu'il faut faire, exécute et produit des résultats. Entre les sessions, l'état est capturé dans les journaux de session et les documents de suivi.

Si ces documents sont inexacts, la session suivante démarre avec de mauvaises hypothèses. Claude pourrait réimplémenter quelque chose qui fonctionne, ignorer quelque chose de cassé, ou estimer l'effort incorrectement. La solution que nous avons adoptée après la session 079 était triple :

1. Exécuter les tests d'abord. Chaque session commence par cargo test pour établir une base de référence.
2. Chercher avant d'implémenter. Avant d'écrire du nouveau code, chercher les implémentations existantes de la même fonctionnalité.
3. Mettre à jour le suivi de manière atomique. Quand une tâche est complétée, le fichier de suivi est mis à jour dans le même commit.

Ces pratiques ont réduit la dérive de documentation dans les sessions suivantes et rendu l'estimation de progression plus fiable.

La session a prouvé un principe qui s'applique bien au-delà de FLIN : parfois le travail le plus productif n'est pas d'écrire du nouveau code, mais de comprendre le code que vous avez déjà écrit. La vérification est une implémentation. La validation est une progression. Et l'hypothèse la plus dangereuse dans tout projet est que votre document de suivi est exact.

Ceci est la partie 9 de la série « Comment nous avons construit FLIN » sur le modèle temporel, documentant l'audit de précision du suivi qui a révélé des progrès cachés et validé les cas limites temporels.

Navigation dans la série : - [046] Chaque entité se souvient de tout : le modèle temporel - [047] Historique des versions et requêtes de voyage dans le temps - [048] Intégration temporelle : des bugs à 100 % de couverture de tests - [049] Destroy et Restore : la suppression douce bien faite - [050] Filtrage et tri temporels - [051] Fonctions de comparaison temporelle - [052] Accès aux métadonnées de version - [053] Arithmétique temporelle : ajouter des jours, comparer des dates - [054] Précision du suivi et validation (vous êtes ici) - [055] Le modèle temporel complet : ce qu'aucun autre langage n'offre