v1.10 · /sdd trace

Traçabilité machine-vérifiable — Intent ↔ SPEC ↔ Code ↔ Tests

Depuis la v1.10, le Drift Lock n'est plus seulement un rituel humain : il est mesuré algorithmiquement. Quatre annotations dans le code, une matrice générée par npx aiad-sdd trace, et une GitHub Action qui bloque toute PR présentant un gap — la chaîne Intent ↔ SPEC ↔ Code ↔ Tests devient vérifiable par une machine.

Du rituel humain à la mesure algorithmique

Le Drift Lock exigeait déjà que code et SPEC soient synchronisés dans la même PR — mais cette vérification reposait sur la rigueur du Product Engineer. La traçabilité machine-vérifiable la rend objectivable : chaque fichier de code applicatif déclare la SPEC qu'il sert, chaque SPEC pointe son Intent parent, chaque test couvre une SPEC identifiée. L'absence d'annotation n'est pas un détail cosmétique — c'est un drift latent qui se détecte au commit, pas en production.

Les quatre annotations

L'exemple canonique en JSDoc :

/**
 * @intent INTENT-042
 * @spec SPEC-042-1-flow-auth
 * @verified-by tests/auth/oidc.test.ts
 * @governance AIAD-RGPD
 */

Les annotations sont acceptées dans les JSDoc, les commentaires // et #, et les docstrings Python """…""" — le scanner est agnostique du langage. Seul @spec est obligatoire : 100 % des fichiers de code applicatif doivent en porter au moins un (les fichiers d'infrastructure pure peuvent être whitelistés explicitement). Un test peut être lié à une SPEC par deux mécanismes au choix : annotation @spec côté test, ou @verified-by côté code.

Générer la matrice : npx aiad-sdd trace

npx aiad-sdd trace                  # Markdown + JSON + HTML dans .aiad/metrics/traceability/
npx aiad-sdd trace --json           # JSON brut sur stdout (CI)
npx aiad-sdd trace --fail-on-gap    # Exit 1 si gap bloquant détecté (CI)

Le scan croise les annotations du code avec .aiad/intents/ et .aiad/specs/ et produit deux matrices. La matrice Forward (Intent → SPEC → Code → Tests, une ligne par SPEC) vérifie que chaque intention validée est implémentée et testée. La matrice Backward (Tests → Code → SPEC → Intent, une ligne par test) débusque les tests sans SPEC parent — qu'on annote, ou dont on documente la nature (exploratoire, benchmark). Chaque snapshot est persisté dans .aiad/metrics/traceability/, ce qui permet de mesurer l'adoption dans le temps.

Les trois familles de gaps

Quand le scan ne peut pas conclure — fichier illisible, annotation pointant vers une SPEC inexistante, index corrompu — le verdict est UNKNOWN, jamais un OK silencieux : c'est la politique JNSP fail-closed, et --fail-on-gap traite UNKNOWN comme un GAP.

La GitHub Action sdd-trace.yml

La remédiation est toujours actionnable : Intent sans SPEC → /sdd spec ou archiver l'Intent ; SPEC validée sans code → implémenter (et annoter) ou repasser la SPEC en draft ; code orphelin → créer la SPEC manquante ou corriger l'ID ; code annoté sans test → ajouter un test annoté @spec ou un @verified-by.

La skill traceability

La logique est portée par la skill traceability, invoquée par /sdd trace, /sdd drift-check, /sdd validate, /sdd audit et le hook pre-commit — en plus de la GitHub Action. La skill drift-detection la compose sans dupliquer sa logique : un gap détecté par la matrice fait échouer le drift-check. C'est l'aboutissement de la composition de skills du SDD Mode : une seule convention d'annotations, lue partout, de l'éditeur à la CI.

Au-delà du contrôle de drift, cette trace est un élément de preuve : elle relie chaque ligne de code à une intention humaine identifiée et à un périmètre délégué. Voir la trace comme preuve sur la page Autonomie de l'agent.