check_docs_links.py : les chemins de doc cites dans les commentaires de code echappent a l'organe (C#, Lean, Python) #24410

Angle mort de scripts/check_docs_links.py, releve par ai-01 en cloture des levees de ce cycle (DM c2760-ai01-po2027-lifts-1, 2026-11-03T09:32Z), avec la consigne : ouvrir l'issue avec un cas reproductible et la commande qui le montre, et verifier si les autres langages de commentaire ont le meme trou avant d'ecrire le correctif — un seul correctif doit couvrir la classe.

Constat : l'organe ne lit que du markdown

_iter_scanned_files (scripts/check_docs_links.py) collecte rglob("*.md") sur docs/, .claude/rules|agents|skills/, plus README.md, les slides/<deck>/slides.md et une liste explicite (CLAUDE.md, index.md, PARCOURS.md, BOOK_MAPPING.md). Un fichier .cs, .lean ou .py n'est jamais ouvert : un chemin de doc qui y est cite est structurellement invisible a l'organe, qu'il soit vivant ou mort.

Cas reproductible (mesure du 2026-11-03, origin/main)

Quatre citations de doc en commentaire de code pointent un chemin qui n'existe plus, parce que la cible a deménagé :

Commande qui montre le trou (la cible est absente au chemin cite, la citation est la, et l'organe ne la voit pas) :

git cat-file -e HEAD:docs/RECAP_KEEPERS_V2.md ; echo "cible rc=$?"    # rc=1, absente au chemin cite
git ls-files | grep -F "docs/RECAP_KEEPERS_V2.md"                     # la cible existe ailleurs
sed -n '3p' "MyIA.AI.Notebooks/QuantConnect/ML-Training-Pipeline/scripts/_archive/s2_gsp_cross_asset_vol.py"
python scripts/check_docs_links.py --quiet ; echo "organe rc=$?"      # voir la correction ci-dessous

Correction de ce body (mesure, 2026-11-03). La premiere redaction annoncait « organe rc=0 ». C'est faux : python scripts/check_docs_links.py --quiet sur un main propre rend rc=1 — il y a donc aujourd'hui des liens markdown casses que le scan plein ne tient pas pour excuses (baseline_docs_links.json), independamment de cette issue. Le trou decrit ici ne depend pas de ce rouge : il tient a ce que _iter_scanned_files ne collecte que des *.md, donc aucun de ces quatre cas n'est meme un candidat pour l'organe, qu'il rende 0 ou 1. La formulation correcte est : l'organe ne peut pas voir ces citations, pas l'organe est vert.

La classe est inter-langages — mesure, pas supposition

Chemins de doc cites hors tests, sur origin/main (comptage par occurrence) :

Les 4 citations C# sont aujourd'hui vivantes (docs/reference/backtester-e2-cadrage.md, docs/reference/backtester-e2-svm-kernel.md) : c'est precisement pourquoi l'angle mort est passe inapercu — un C# sain aujourd'hui n'est pas un C# surveille. Le trou est le meme dans les trois langages, donc un seul correctif le couvre, selon la consigne d'ai-01.

Contrainte de conception : elargir le glob tel quel produit 118 faux positifs

Un scan naif des chemins docs/…md / .claude/…md cites dans les fichiers de code rend 118 chemins absents. Ils se rangent en trois familles qui ne sont pas des liens de doc, et qu'un correctif doit exclure par construction plutot que par liste :

1. Fixtures de test — docs/132.md, .claude/rules/foo.md, .claude/agent-memory/note.md : chemins volontairement inexistants, ecrits dans scripts/tests/. Exclure les arbres de tests, ou exiger un contexte de commentaire hors fixture.
2. Sorties generees — docs/M13_MS_HAR.md est aussi ecrit par gen_m13_doc_section.py : un chemin en position de sortie (--out, open(..., "w"), Path(...).write_text) n'est pas une citation.
3. Chemins d'un depot tiers — lean/docs/132.md appartient a openai/math, pas a CoursIA : un chemin qualifie par un autre depot ne se resout pas contre notre arbre.

La mesure ci-dessus a ete obtenue en classant le contexte ligne par ligne (commentaire vs code, citation vs sortie, arbre de test exclu) ; sans ce classement, le chiffre brut est 118 et n'a aucune valeur de signal.

Attendu

1. Etendre _iter_scanned_files (ou une passe dediee) aux commentaires des fichiers de code, avec les trois exclusions ci-dessus — un correctif unique, pas un par langage.
2. Le verdict doit rester differentiel : une citation qui pointait deja un chemin mort sur main ne doit pas rougir une PR sans rapport (meme mecanisme que --base REF pour les liens markdown, ci(#docs-links): la reference des liens casses est un fichier fige a 0 — un lien casse sur main rougit check-links, Always-on guards et PR gate de TOUTE PR ouverte #15766).
3. Brancher le controle positif existant (--expect-broken N) sur le nouveau chemin de detection : sans lui, « 0 casse » reste indiscernable d'un chemin de detection mort — c'est exactement la lecon de l'organe lui-meme.

Sans parent : angle mort releve par ai-01 au DM c2760-ai01-po2027-lifts-1 (2026-11-03) ; aucun EPIC tracé ne porte la classe « organes de liens de documentation ».