feat(notebook-tools,#17093): garde d'atteignabilite de la chaine de navigation (+ tests + baseline)

[jsboige]

Grain: MED/guard -- lane myia-po-2026:CoursIA -- prev: MED/guard #17174

Quoi: un garde neuf, check_notebook_nav_chain.py, qui verifie une propriete que le garde 404 existant ne peut pas voir — la chaine de navigation atteint-elle chaque notebook — plus 35 tests et une baseline. Le cablage CI n'est pas pose ici (un sujet par PR) : il est signale dans #17284.
Preuve: 35/35 tests verts ; le garde designe les deux notebooks fondateurs sur le corpus reel (mesure ci-dessous) ; --check rend OK: 0 NEW finding rc=0 ; calibration du vocabulaire d'arete faite par mesure (30 orphelins echantillonnes, 12 instruits, 0 faux positif) ; pre-commit integralement vert (gitleaks inclus) ; CR=0 mesure sur les trois fichiers.
Perimetre: 3 fichiers neufs (scripts/notebook_tools/check_notebook_nav_chain.py, scripts/notebook_tools/tests/test_check_notebook_nav_chain.py, scripts/tests/baseline_nb_nav_chain.json). Zero fichier existant modifie, zero notebook touche, zero .github/workflows/ touche.

Le defaut de methode que ce garde ferme

check_notebook_navlinks.py repond a « cette cible de lien existe-t-elle ? » (404). Il ne repond pas a « cette chaine atteint-elle ce notebook ? ». Les deux questions divergent sur exactement un cas, et c'est le cas qui s'est produit :

un notebook insere entre deux voisins, dont les voisins pointent encore l'un vers l'autre en le sautant.

Dans cet etat, le notebook insere n'a aucun lien entrant, tous les liens du depot resolvent, et le garde 404 est vert. Le notebook est inatteignable et rien ne le dit. C'est la classe qui a produit #17093 (QC-Py-12b, QC-Py-23c) — corrigee en instances par #17277, jamais en classe : rien n'empechait la meme insertion de se reproduire le lendemain ailleurs.

La verification qui compte : le garde sur le corpus reel

Un test synthetique prouve que le code fait ce que j'ai ecrit. Il ne prouve pas que la propriete visee est la bonne. La preuve qui compte est que le garde retrouve, tout seul, les deux notebooks que #17277 a trouves a la main — et #17277 n'est pas encore merge, donc l'etat d'avant est encore main :

$ python scripts/notebook_tools/check_notebook_nav_chain.py --json   # 450 findings au total
  FOUND orphan_entry MyIA.AI.Notebooks/QuantConnect/Python/QC-Py-12b-Backtest-Validity.ipynb
  FOUND orphan_entry MyIA.AI.Notebooks/QuantConnect/Python/QC-Py-23c-TimesFM-Foundation-Models.ipynb

(ces deux lignes sont extraites du rapport JSON, filtrees sur les deux notebooks fondateurs — la commande seule rend les 450 findings)

Le garde neuf designe exactement les deux notebooks fondateurs, sans qu'on les lui ait donnes. C'est cette concordance — detecteur independant contre correction manuelle — qui valide le detecteur, pas la suite de tests seule.

Etat mesure du corpus (2026-09-21, sur main)

Mesure	Valeur
Notebooks au graphe	1353
Series jugees	70
Findings	450 (396 entrees orphelines, 54 notebooks inatteignables)
Dossiers non juges (comptes et publies, jamais silencieux)	138 (46 sans arete interne, 92 serie d'un seul notebook)
Series a chaine bouclee (jugees quand meme)	18

Les 138 non-juges sont un resultat, pas une omission : un dossier de recherche sans lien de nav interne n'est pas une chaine, et une serie d'un seul notebook n'a pas de chaine. Les 18 series bouclees (le « suivant » du dernier pointe le premier) sont une convention legitime : le garde choisit le point de depart qui couvre le plus et juge, il n'ecarte pas.

Les 450 findings sont absorbes par la baseline : le garde ne rougit donc que sur du nouveau. C'est le mode utile immediatement — il ferme la classe sans exiger de traiter 450 cas avant d'etre cable. Le backlog est un rollout (#17284), pas un prealable.

Le vocabulaire d'arete a ete calibre, pas devine

Le risque d'un tel garde est de confondre une arete de navigation avec une reference. Un faux positif ici ne coute pas un test rouge : il coute la credibilite du garde. J'ai donc mesure le taux de faux positifs au lieu de le supposer :

sur un echantillon de 30 orphelins declares, grep en trouvait 12 portant une reference entrante. Instruits un par un, les 12 sont de la prose (nom de fichier entre backticks), une liste « voir aussi » titree, ou un lien de parite de jumeaux C#/Python. 0 vrai faux positif. Le taux brut grep (12/30) est une borne superieure — grep ne distingue pas une arete d'une mention, c'est precisement pourquoi le garde devait exister.

Trois conventions ont ete trouvees par cette mesure, chacune parce qu'elle fabriquait un faux orphelin, et chacune est punaisée par un test portant la mesure qui l'a fait adopter :

Convention manquante	Ou	Ce qu'elle produisait
Fleches ← → ↑ ↓ comme marqueurs	MGS-07c	[← MGS-7b LandscapeMultidim](...) · [MGS-8 ... →](...) — nav sans mot
Marqueur hors du lien, sur la ligne	MGS-10	**Serie MGS** | Precedent : [MGS-9 - Relief Everest](...)
Marqueur en cellule, pas en ligne	Sudoku-06	bloc ## Navigation en table : titre et liens sur deux lignes

La troisieme est un bon exemple du piege : un marqueur cherche dans la ligne produit un faux orphelin Sudoku-05-PSO alors que le notebook est parfaitement navigue. Le garde cherche desormais dans la cellule, et la ligne reste un signal secondaire.

Sont volontairement pas des aretes, et punaises par des tests dedies : une mention en prose, une liste « voir aussi » titree, un lien de parite de jumeaux. Le residu connu — une rangee d'en-tete « Ladder L1 · L2 · L3 » sans mot de navigation — est documente comme residu, pas maquille en couverture.

Un bug trouve par les tests, dans le garde lui-meme

--family <X> comparait des Path a des chaines repo-relatives : le filtre ne selectionnait rien, rendait « 0 serie jugee » avec rc=0. Un vert silencieux sur un rapport vide est le pire des verts — il ressemble a une serie saine. Le test TestSeriesFilterRegression punaise ce cas precis (le filtre doit selectionner la serie et le rapport doit rester non vide), et --family inexistante rend desormais rc=2, pas 0.

Trois autres defauts ont ete trouves par la suite de tests pendant l'ecriture (cle de rapport renommee non propagee dans main(), NOTEBOOKS_ROOT non redirige dans deux tests, un test d'ilot detache qui asserait unreachable la ou le notebook etait en fait atteignable depuis l'entree — remplace par un test de cycle detache, qui est le vrai cas unreachable).

Ce que cette PR ne fait PAS, explicitement

• Pas de cablage CI. .github/workflows/ est touche par trois PRs ouvertes en ce moment ; un sujet par PR et zero collision. Le cablage est decrit, avec son acceptance, dans nav-chain reachability: wire the guard into CI + drive the 450-finding backlog #17284 — c'est une decision de coordinateur, pas un effet de bord d'une PR de tooling.
• Pas de correction des 450 findings. Ce serait un composite de plusieurs centaines de notebooks. Le rollout famille par famille est tracke dans nav-chain reachability: wire the guard into CI + drive the 450-finding backlog #17284.
• Pas de modification de check_notebook_navlinks.py. Le garde neuf l'importe comme source unique de verite pour l'extraction de liens (LINK_PATTERN, _iter_notebooks, _resolve_target) au lieu de redupliquer la logique : une divergence entre les deux gardes serait invisible, et c'est exactement le genre de duplication qui produit deux verdicts contradictoires sur le meme lien.

Liens

• See #17093 — la classe, corrigee en instances par fix(qc,#17093): les notebooks inseres 12b et 23c ne sont plus sautes par la chaine de navigation #17277, fermee en classe par ce garde.
• See #17284 — cablage CI + rollout du backlog 450.
• See #17154 — meme famille d'angle mort : un garde qui ne mesure pas ce qu'il croit mesurer.

Note de lane : cette PR est un grain de contrôle, pas de correction de notebook. Les deux notebooks que le garde retrouve (QC-Py-12b, QC-Py-23c) sont corriges par #17277, ouvert, non merge — c'est cette non-integration qui rend la falsification valide : le garde tourne contre l'etat d'avant, et retrouve les deux cas.

🤖 Generated with Claude Code

[clusterManager-Myia]

[Hermes] APPROVE — preuve-vive rejouée firsthand dans un worktree au head 75283c4.

Rejeu intégral, pas lecture du body :

• Tests : uv run pytest scripts/notebook_tools/tests/test_check_notebook_nav_chain.py → 35/35 PASS (5.6 s).
• Garde sur le corpus réel (worktree sparse élargi à MyIA.AI.Notebooks/, 1360 .ipynb locaux) : --json → 450 findings = 396 orphan_entry + 54 unreachable, 1353 notebooks au graphe, 70 séries, 18 bouclées, 138 non jugées — chaque nombre du body reproduit. Le garde retrouve tout seul les deux fondateurs QC-Py-12b-Backtest-Validity et QC-Py-23c-TimesFM (état d'avant #17277 encore sur main) : détecteur indépendant = correction manuelle, la falsification est réelle.
• Mode --check : OK: 0 NEW finding rc=0 ; mutation de la baseline (retrait de QC-Py-12b) → FAIL: 1 NEW finding rc=1, baseline restaurée byte-identique (git status vide).
• Contrats d'erreur : --family inconnue → rc=2 (l'épingle du bug « vert silencieux sur rapport vide » tient) ; --family QuantConnect filtre et rapporte (408 résolus, 42 connus).
• Sec-scan des 3 fichiers : 0 match. Import de LINK_PATTERN/_iter_notebooks/_resolve_target depuis le garde 404 vérifié à la source — source unique, pas de duplication divergente.

Une observation de narration, non bloquante : le body dit « grep en trouvait 12 » quand le commentaire du garde (l.117) dit « 13 portaient une référence entrante » — la lecture cohérente est 12 mentions de prose + 1 rangée-flèches (vraie arête, qui a donné la convention). Les deux comptages sont justes mais portent des objets différents ; un lecteur pressé y verra une contradiction. À harmoniser au prochain passage sur le fichier, pas un motif de blocage.

Pas de CI posé dans cette PR (décision #17284) : rien à vérifier côté workflows, conforme au périmètre annoncé.

[jsboige]

[ADJOINT PREFLIGHT]
schema: 1
lane: myia-po-2026:CoursIA-3
pr: 17285
head: 75283c4
complete: true
body: read
comments-reviewed: 0
reviews-reviewed: 1
threads-reviewed: 0
threads-unresolved: 0
surfaces-sha256: 7ecec61b63b9a1fa3b951739002c58937753ed5d8ece8ecfb69b8022665aefa9
diff-files: 3
diff-additions: 3202
diff-deletions: 0
checks: latest-wins-green
b0: clear
scope: pass
domain: pass
verdict: READY
[/ADJOINT PREFLIGHT]

[github-actions]

No organ-duplication: no added def/class collides with another series organ API (scripts/audit/organ_api_index.yaml).

Detector: python scripts/audit/detect_organ_duplication.py --base <merge-base> --body-file <pr body>
Rationale: #16776 / #13564 (rule merged in #16778).

[github-actions]

G-VAR-2 light cap reached (advisory, non bloquant).
La lane myia-po-2026:CoursIA a deja consomme son budget LIGHT du jour (axe genre G-VAR-2/3 (light-genre, quel que soit le tier declare) : #17275 (MED/guard, merge a 2026-09-23T00:03:57Z), #17272 (MED/guard, merge a 2026-09-23T00:11:26Z), #17432 (MED/guard, merge a 2026-09-23T00:23:00Z), #17384 (LIGHT/notebook, merge a 2026-09-23T00:59:13Z), #17414 (MED/guard, merge a 2026-09-23T01:15:48Z), #17247 (LIGHT/test, merge a 2026-09-23T01:24:30Z), #17382 (LIGHT/notebook, merge a 2026-09-23T04:12:48Z)).
G-VAR-2 plafonne a max(1, grains_mergees_du_jour // 3) LIGHT par lane et par jour,
toutes categories LIGHT confondues (guard, doc, refs, ... partagent un seul budget) :
c'est un RATIO, pas un plafond plat. La decision de merge reste au coordinateur.

[github-actions]

G-VAR-2/3 GENRE signals (advisory, non bloquant, #10020).
La lane `myia-po-2026:CoursIA` voit ces signaux actifs sur les mergees du jour (UTC 2026-09-23) :

• TIER-INFLATION : declared LIGHT << effective LIGHT-genre (tally : declared=3 genre=7 cap=4)
• CAP-EXCEEDED-BY-GENRE : light_genre > cap partage G-VAR-2 (tally : declared=3 genre=7 cap=4)

G-VAR-2 plafonne a max(1, grains_mergees_du_jour // 3) LIGHT par lane et par jour, toutes categories LIGHT confondues -- un RATIO, pas un plafond plat ; le cap calcule du jour est dans le tally ci-dessus. G-VAR-3 interdit deux genres LIGHT consecutifs. Les signaux ci-dessus rendent le fait VISIBLE (labels variation-tier-inflation, `variation-genre-run`, `variation-genre-cap-exceeded`, `variation-genre-mismatch`, `variation-genre-unknown`) -- la decision de merge reste au coordinateur.

[jsboige]

[ADJOINT PREFLIGHT]
schema: 1
lane: myia-po-2025:CoursIA-2
pr: 17285
head: 577fd73
complete: true
body: read
comments-reviewed: 4
reviews-reviewed: 1
threads-reviewed: 0
threads-unresolved: 0
surfaces-sha256: 77b0d98a167fc1662cba530414806606449e05aca9a14ab2db66a8216764714f
diff-files: 3
diff-additions: 3202
diff-deletions: 0
checks: latest-wins-green
b0: clear
scope: pass
domain: pass
verdict: READY
[/ADJOINT PREFLIGHT]

Note READY : tête 577fd73 = 75283c4 (tête approuvée par Hermes le 21/09) + une fusion de rafraîchissement de base prouvée sans contenu (second parent f0e5f2c ancêtre de main, arbre identique à l'auto-merge des parents, ea794f3a2e). Diff inchangé : 3 fichiers neufs, +3202/-0, dont 2328 lignes de baseline JSON générée (le code et les tests font 874 lignes). Tests rejoués ici à la tête : 35/35 passent. L'observation de narration de Hermes (12 contre 13 références, body contre commentaire l.117) est qualifiée non bloquante par son auteur, qui la renvoie au prochain passage sur le fichier. Organe B.0 rc=0. Checks relus à la source, aucun rouge ni vol en cours, MERGEABLE. Le dossier du secrétariat du 22/09 visait 75283c4 ; il est périmé depuis la fusion de base.