Aller au contenu

Contrat de données (workspace-data-contract)

Vos séances, vos nuits et vos plans restent des fichiers Markdown lisibles. Mais chaque fichier écrit par un agent commence désormais par un petit bloc de données : c'est lui que lisent le tableau de bord et la comparaison de parcours, jamais la prose.

Vos données, votre sentier

En vidéo · Étape 12 · 1 min 42

Vos données, votre sentier — Vos données restent des fichiers Markdown chez vous : un bloc validé, un index jetable, un tableau de bord local, et ce qui quitte la machine.

Regarder · English · Toutes les vidéos

À quoi ça ressemble

# Séance du 2026-09-20 — Trail de Tournai

```arc
{"arc": 1, "kind": "activity", "date": "2026-09-20", "sport": "trail",
 "distance_m": 12300, "duration_s": 5218, "elevation_gain_m": 480, "avg_hr_bpm": 148}
```

L'analyse du coach, en français, comme avant.

Le bloc est du JSON. Ses clés sont en anglais et ne changent jamais, quelle que soit la langue de vos documents ; ses valeurs sont en unités SI (mètres, secondes, bpm), même si vous avez choisi les unités impériales — la conversion se fait à l'affichage.

Pourquoi

Avant ce contrat, les chiffres se lisaient dans des tableaux et des titres français. Passer [language].documents à "en" suffisait à faire disparaître toutes vos séances de la comparaison de parcours, sans le moindre message. Un bloc typé ne dépend ni de la langue, ni de l'ordre des colonnes, ni de la formulation du modèle.

Les types de fichiers

Type Fichier
activity activities/AAAA-MM-JJ_<type>.md
health medical/AAAA-MM-JJ_health.md — sommeil, HRV, FC de repos, readiness, poids et sa provenance (weight_origin, #222), verdict du jour, contexte du cycle (opt-in, #166)
weather medical/AAAA-MM-JJ_meteo.md
week planning/Semaine_AAAA-MM-JJ.md, daté du lundi — un fichier par semaine, ou un seul fichier multi-semaines (bloc weeks, un plan de 10 semaines peut tenir dans 1 fichier) — séances datées, lieu de la semaine
nutrition nutrition/AAAA-MM-JJ_nutrition.md
report rapports/…
gear_inspection gear/AAAA-MM-JJ_<gear_id>_inspection.md — inspection photo d'une paire de chaussures (#135), photos dans gear/photos/
shoe_spec gear/specs/<gear_id>.md — fiche de caractéristiques d'une paire (#298) ; porte aussi son bilan de retraite verdict (#299)
shoe_recommendation gear/AAAA-MM-JJ_shoe_recommendation_<rôle>.md — recommandation de chaussures montrée à l'athlète et validée par lui (#302)
course_eval planning/…_evaluation_parcours_<lieu>.md
race_plan plan de course dans planning/
decision planning/AAAA-MM-JJ_decision_<slug>.md — traçabilité d'un ajustement (garde-fou, bilan matinal, blessure…), un fichier par décision

Dans un fichier activity, la clé facultative shoe_feedback (#299, saisie par /log) porte le retour de chaussant de la séance ; elle exige un gear_id et ne remplace jamais la douleur (pain, dans le fichier santé). Voir Choisir ses chaussures.

Votre profil (planning/Runner_Profile.md) et votre objectif (planning/active_objective.md) n'ont pas de bloc : vous les éditez à la main, et leurs puces suffisent. Gardez simplement les libellés du modèle.

Dynamique de course (clés optionnelles d'une séance)

Depuis #151, une séance de course peut porter les moyennes de la dynamique de course Garmin, en unités SI : avg_ground_contact_s (temps de contact, secondes), avg_stance_balance_pct (balance du temps de contact, %), avg_vertical_oscillation_m (mètres), avg_vertical_ratio_pct (%) et avg_step_length_m (mètres). Une clé absente veut dire « non mesuré » — jamais 0, jamais 50 pour une balance. Ce n'est qu'un repli : quand les échantillons FIT sont ingérés, arc_index.py gait-summary calcule sa propre moyenne et c'est elle qui fait foi. Aucun agent ni script n'écrit ces clés automatiquement : elles servent de repli pour des valeurs saisies à la main ou héritées d'anciens fichiers. Une balance hors de 30 à 70 % déclenche un avertissement du validateur et est ignorée par la synthèse. Voir la carte Foulée.

Vérifier un fichier

python3 scripts/arc_index.py --validate medical/2026-09-20_health.md

Les agents le font après chaque écriture. Le schéma complet, clé par clé, est dans skills/workspace-data-contract/SKILL.md.

Et les fichiers écrits avant ?

Ils restent lus, au mieux, et le tableau de bord les signale comme incomplets. /arc-backfill les met au contrat, par lots.