View as:

ADR-002 : Cartographie opérationnelle des sources de données (M3)

Statut

Accepté — 2026-04-14

Contexte

Le sprint M1 (cf. docs/sprint/2026-04-14-maqi-sprint.md) a livré un catalogue curé des providers nommés par Charles-Albert dans son doc gdrive : docs/providers/catalog.yaml (22 entrées à l'époque, 28 au 2026-04-16 après ajout des legacy dumps et des sources classe III), une vue humaine docs/providers/README.md, et une copie markdown versionnée des docs CAL source (docs/cal/).

Ce catalogue est une photographie d'intention. Il ne dit pas, pour chaque source :

Sans cette information, chaque décision d'achat ou de négociation repart de zéro, et la mémoire du dossier vit implicitement dans la tête de Charles-Albert — ce qui est fragile et peu scalable.

L'effort M3 a capturé et évalué cette dette sur les trois axes : explore (ce qu'il y a à regarder), validate (ce qu'il y a à relire), et negotiate (ce qu'il y a à demander).

La présente ADR tranche le format à retenir pour la cartographie opérationnelle, et fixe les contraintes d'écriture qui s'appliqueront à chaque tâche enfant.

Décision

1. Format retenu : B (principal) + A (squelette enrichi) + C (vue dérivée)

La cartographie M3 est portée par trois artefacts composables, chacun jouant un rôle distinct :

flowchart LR
    cal["docs/cal/datasets-pipeline.md<br>(CAL source, read-only)"]
    yaml["docs/providers/catalog.yaml<br><i>squelette enrichi</i>"]
    md["docs/providers/&lt;id&gt;.md<br><i>un fichier par provider</i>"]
    matrix["docs/providers/cartography.md<br><i>vue matricielle dérivée</i>"]

    cal --> yaml
    yaml --> md
    md --> matrix
    yaml --> matrix

    style cal fill:#eef,stroke:#448
    style yaml fill:#dfd,stroke:#0a0
    style md fill:#dfd,stroke:#0a0
    style matrix fill:#ffe,stroke:#cc0

2. Squelette imposé du markdown par provider (Option B)

Tous les docs/providers/<id>.md suivent le même squelette, pour rendre la cartographie lisible de façon uniforme :

---
id: <slug>
name: <display name>
operational_status: not_started | explored | validated | in_negotiation | blocked | rejected
last_reviewed: YYYY-MM-DD
owner: <repo handle or "unassigned">
class: I | II | III | IV   # cf. idée step 2
upstream: docs/providers/catalog.yaml#<id>
linked_deliverables: [<tag>, ...]
---

# <Nom du provider>

## Explore

<ce que le provider annonce livrer, où, comment, sous quelle licence.
Minimum attendu : URL, type de livraison, fréquence, coverage, CGU.>

## Validate

<pour les sources déjà en notre possession : ce qu'on a vraiment
regardé. Schéma observé, compte de lignes, fenêtre temporelle,
anomalies. *Aucun extrait de données payées — uniquement des résumés.*>

## Negotiate

<log daté des actions de négociation. Lignes du type :
`2026-04-14 — email envoyé à X, en attente de réponse`.
*Aucun prix, aucune condition commerciale, aucun draft NDA.*>

## Decisions

<liens vers les ADR ou issues GitHub qui s'appuient sur cette source.>

3. Contraintes d'écriture (non-négociables)

Reprises de docs/cal/tech-solutions.md et du capture step :

4. Découpage en tâches enfants (par classe, pas par provider)

Pour éviter l'inflation du backlog (28 tâches = 28 worktrees = ingérable), la cartographie est découpée en 4 tâches enfants, une par classe (cf. idée step 2). Chaque classe est tackle-able indépendamment, avec ses propres gates de sortie.

EnfantScopeN providersEffort estiméBloquant
task-m3-class-1Classe I — owned, needs validation (5 flux S&P Global)5\(\approx\) 15 hAccès local Xpressfeed
task-m3-class-2Classe II — owned legacy, needs verification (RavenPack dump, Databento NASDAQ)2\(\approx\) 3 hNon
task-m3-class-3Classe III — public URL, needs lightweight exploration (8 sources publiques)8\(\approx\) 3 hNon
task-m3-class-4Classe IV — opaque / contact-only, needs email log (7 sources à négocier)7< 1 h actif + asyncDépend de tiers

Chaque enfant a pour Definition of Done :

  1. Tous les markdown docs/providers/<id>.md de sa classe sont créés (squelette rempli au moins pour Explore).
  2. Les entrées YAML correspondantes portent operational_status, last_reviewed, et detail_doc.
  3. La vue matricielle docs/providers/cartography.md reflète le nouvel état de la classe.
  4. Tous les enfants nucléés portent le tag temp:warm (contrainte formula idea-to-plan).

5. Règle de resynchronisation

Quand scripts/sync-cal-docs.sh est ré-exécuté et fait apparaître un provider non présent dans catalog.yaml :

  1. Le provider est ajouté manuellement au YAML avec operational_status: not_started.
  2. Un markdown docs/providers/<id>.md vide (squelette seul) est créé.
  3. Le provider est classé (I / II / III / IV) selon le même critère que step 2 de l'idée.
  4. Si la classe est I, II ou IV, une nouvelle tâche enfant de la classe correspondante est nucléée (warm).

Cette règle n'est pas automatisée dans le sprint M3 : elle est documentée ici pour les sprints futurs, et sera reprise par un sprint d'outillage si la fréquence le justifie.

Conséquences

Positives

Négatives

Action à envisager

Références