[EPIC] README ascendant — resynchroniser la hiérarchie (feuilles -> principal) depuis l'évolution du dépôt

[jsboige]

Refonte du 2026-09-25 — un README de série se lit d'abord par ses numéros nus

Décision du mainteneur (2026-09-25), prise après relecture des READMEs réécrits et du catalogue régénéré. Cet EPIC ne se contente plus de resynchroniser les feuilles sur l'état du dépôt : il change leur forme. La doctrine de gradation de #5081 s'applique aux noms de fichiers : les numéros nus portent l'arc narratif, les lettres l'approfondissement. Les READMEs ne l'appliquent pas encore.

Le défaut constaté

• Les accrétions sont présentées comme une séquence. La plupart des READMEs de série listent 01, 01b, 01c, 02… dans une même table, au même niveau. Un lecteur qui veut suivre le parcours léger bute sur la description de chaque approfondissement, comme si tout lire dans l'ordre était le mode normal. Ce n'est pas le cas : on lit les numéros nus, et on ouvre une lettre quand on veut creuser un palier.
• Les paragraphes de complexités différentes sont mêlés. L'introduction, les notes de recherche, le statut de maturité et les détails de formalisation se suivent sans signalétique. Le lecteur ne peut pas choisir la profondeur qui lui convient.
• Des parties centrales sont obsolètes. Elles décrivent des noms, des numéros ou des arcs qui ont changé depuis : renommages [EPIC][#5081] Noms canoniques — padding, titres français et suffixes noyau #11840 et Remise d'aplomb de la nomenclature des notebooks — suffixe noyau, sans-numero, profondeur d'accretion #16231, gradations Complexity [Complexity] Refondre la progression pedagogique de la serie — curriculum en accretion, socle avant le zoo Aaronson #17063, Lean [Lean] Gradation du chemin principal a partir de Lean-10 + sous-series (Lean et IA, Conway, verification, formalisations) — fille #5081 #17545 et Argumentation [Argumentation] Arc narratif a deux dimensions : numeros (du concept d'argument au pipeline) et accretions (theorie, instruments) — fille #5081 #17547.
• Cause outillée : le gabarit de l'agent readme-updater produisait une table plate unique. Il est corrigé par docs(agents,#3973): README de série — parcours principal d'abord, lettres à part, niveaux de lecture signalés #17779.

La forme cible d'un README de série

1. Ouverture (Découverte) : ce que la série enseigne, à qui, avec quels prérequis d'entrée. Les comptes sont délégués au catalogue.

2. « Comment lire ce README » : une phrase qui rappelle le principe des parcours à plusieurs vitesses, avec un lien vers la section racine « Choisir sa vitesse de lecture » (docs(readme,#3973): présenter les trois vitesses de lecture dès le README principal #17781). Puis trois lignes de signalétique. Vous découvrez : lisez le parcours principal. Vous creusez un palier : ouvrez sa section d'approfondissements. Vous cherchez la recherche en cours : sous-séries et « Pour aller plus loin ».

3. Parcours principal : une table qui ne contient que des numéros nus.

   #	Notebook	Ce qu'on y apprend	Public	Pour approfondir

   Les lettres du palier n'y figurent qu'en liens courts, dans la dernière colonne. Les jumeaux Python, C# et Lean partagent une ligne. Qui lit cette table de haut en bas a le parcours complet de la série.

4. Approfondissements : une sous-section par palier (« Autour de 02 »), avec pour chaque lettre ce qu'elle ajoute et les prérequis qu'elle suppose en plus.

5. Sous-séries : leur dossier, le notebook d'escalier (capstone) qui les présente depuis le parcours principal, et leur propre table au même format. La ligne du capstone, dans la table du parcours principal, renvoie à la sous-série. Les lakes d'une sous-série sont présentés dans son propre README, et cités dans la section « Formalisations Lean » de la série mère ([EPIC] Lean — harmoniser Mathlib, mutualiser les checkouts, regrouper les lakes (anti-proliferation) #4362 c.5829716177).

6. Installation, puis Pour aller plus loin (niveau Recherche : formalisations, statut de maturité, notes techniques), puis Ressources.

7. Les lakes Lean ne sont jamais une étape du parcours. Un lake est l'outillage d'un notebook, ni un numéro ni une lettre. La table du parcours principal n'en nomme aucun. Un lake se présente dans l'approfondissement du notebook qui le consomme, puis dans une seule section « Formalisations Lean » sous « Pour aller plus loin », qui renvoie au LEAN_INVENTORY.md de la série sans le recopier. Où vivent physiquement les lakes, et lesquels se regroupent : arbitrage sur [EPIC] Lean — harmoniser Mathlib, mutualiser les checkouts, regrouper les lakes (anti-proliferation) #4362.

Critères de review :

• la table du parcours principal ne contient aucune lettre en ligne ;
• chaque lettre du dossier figure sous « Approfondissements », rien n'est perdu ;
• chaque section porte son niveau ;
• aucune description ne cite un fichier absent de main ;
• aucun compte en dur ;
• « Comment lire ce README » rappelle le principe et pointe vers la section racine ;
• aucun lake dans la table du parcours principal.

Qui porte quoi

• READMEs stratégiques, portés par ai-01. Ce sont les READMEs de famille, qui agrègent plusieurs arcs ou sous-séries : GameTheory et SymbolicAI en premier, puis Probas, ML, GenAI, Search et IIT, et enfin le hub MyIA.AI.Notebooks/README.md et la racine. Les stratifier par niveau demande le recul d'ensemble de la coordination ; ce travail n'est plus dispatché.
• Le principe des vitesses de lecture est présenté d'abord, pas en dernier. Le README principal l'expose dès « Commencer ici » (docs(readme,#3973): présenter les trois vitesses de lecture dès le README principal #17781) : le parcours principal par les numéros nus, l'approfondissement par les lettres, la recherche par les sous-séries. Il invite le lecteur à choisir son principe de navigation. La racine n'attend donc plus que les feuilles soient toutes réécrites pour annoncer la forme qu'elles adoptent.
• Feuilles d'une seule série, portées par les lanes. Elles suivent la forme ci-dessus : le gabarit corrigé la produit, et l'auditeur la vérifie.

Séquencement par série

Le README d'une série passe en dernier dans l'arc de cette série :

• gradation décidée, renommages en cours (Complexity, Lean, Argumentation) : la refonte du README accompagne la PR qui clôt les renommages, ou la suit immédiatement ;
• noms stables, gradation déjà conforme : refonte tout de suite ;
• gradation à lire (procédure de [EPIC] Nommage canonique et parcours des notebooks — numéros, accrétions, noyaux et catalogue #5081) : pas de refonte de forme avant la décision. En attendant, seules passent les corrections de faits faux (lien mort, nom disparu).

Le suivi par série vit dans la table de relance de #5081.

---

Corps précédent (2026-09-02) conservé intégralement ci-dessous. Sa méthode ascendante et ses contraintes HARD restent valides. La partition lane-alignée est amendée par « Qui porte quoi » ci-dessus.

État au 2026-09-02 — la « DÉRIVE CONFIRMÉE » de ce corps a été corrigée le lendemain, et par le haut

Passe de curation (défaut #13906). Cet EPIC est le cas d'école du défaut : sa section « État mesuré de la racine — 2026-08-30 » est datée, honnête et méthodique, elle porte le mot DÉRIVE CONFIRMÉE en gras — et elle décrit un état qui a cessé d'exister le lendemain. Une lane qui la lit aujourd'hui part corriger deux chiffres qui n'existent plus.

Ce que la section du 30/08 annonçait, et ce qu'on mesure aujourd'hui

Constat du 30/08	Mesure du 2026-09-02
README.md annonce 1 024 notebooks (catalogue : 1 064, écart +40)	le README racine n'annonce plus aucun compte de notebooks
README.md annonce 22 lakes Lean 4 à deux endroits	git show origin/main:README.md | grep -c '22 lakes' → 0
dernier commit sur README.md = 0bbbfb40f (23/08)	quatre commits plus récents, dont celui qui corrige

Le correctif est bfe7be299 — docs(readme): refresh curriculum map and privacy scope (PR #13789, mergée le 2026-08-31), soit un jour après la rédaction de la section.

Et il ne corrige pas les deux nombres : il supprime la classe de défaut. Le README racine ne porte plus de compte en dur du tout ; sa ligne 13 délègue explicitement :

Catalogue vivant — Pour l'inventaire exhaustif […] consultez COURSE_CATALOG.generated.md. Généré par l'automatisation, ce catalogue porte les chiffres et les statuts ; ce README en donne la vue d'ensemble pédagogique.

C'est exactement la contrainte que cet EPIC pose à ses feuilles (« aucun compte en dur dérivant ») — la racine l'a appliquée à elle-même, en déléguant plutôt qu'en re-comptant. C'est le patron à reprendre sur les feuilles restantes, et il vaut mieux que la lettre de l'acceptance : un README qui délègue son compte ne peut plus dériver.

Reste vrai du constat du 30/08 : le corpus compte bien 28 lakefile sur le tree, dont 1 fixture tiers sous agent_tests/prover/session_state/reference_docs/ — 27 lakes propres. Le catalogue annonce 1 090 notebooks (généré le 2026-09-01), pas 1 064 : toute mesure de ce dépôt a une demi-vie de quelques jours, et c'est le seul reproche à faire à une section qui, elle, avait bien daté.

Les cases à cocher ne sont pas l'état d'avancement

Les 8 cases de la checklist ascendante sont toutes vides, et 48 PRs mergées citent cet EPIC (gh pr list --state all --search "3973 in:body" : 48 merged, 0 ouverte, 2 fermées non mergées). Les deux ne se contredisent pas — les cases sont par famille, les PRs par tranche — mais une lane qui lit huit cases vides conclut « rien n'a commencé », ce qui est faux de 48 livraisons.

Deux cases méritent d'être requalifiées dès maintenant :

• la case racine (LAST) : elle n'est plus « à faire après les feuilles ». README.md a été refait par docs(readme): refresh curriculum map and privacy scope #13789 avant que toutes les feuilles soient vertes, et la délégation au catalogue le rend insensible à l'état des feuilles. Ce qui reste sous cette case est le hub MyIA.AI.Notebooks/README.md et les READMEs de section, pas la racine.
• les micro-défauts de compte relevés le 2026-07-15 en commentaire (Search « 13 Python + 16 C# », Tweety « 29 … 16 C# ») sont absents des deux fichiers aujourd'hui : traités, jamais reportés ici.

Contexte amont — trois des cinq références ont bougé

#2959 (Bondareva-Shapley) mergée · #2162 (Conway) fermée · #1206 (Z3.Linq) fermée le 2026-09-01. Restent ouverts : #2874 (Knot, 11 sorry distincts sur 15 au dépôt) et #1203 (MetaGeneticSharp). Une feuille Lean ou MGS écrite aujourd'hui décrit donc un état encore mouvant sur ces deux-là seulement.

Ce qui reste, dans l'ordre où une lane devrait le prendre

1. Les feuilles, avec le patron de la racine : déléguer le compte au catalogue plutôt que le rafraîchir. Une feuille qui cite un nombre s'engage à le re-mesurer indéfiniment ; une feuille qui renvoie au catalogue ne dérive plus jamais.
2. Le hub MyIA.AI.Notebooks/README.md porte un marqueur CATALOG-STATUS (total: 1090) : il est déjà tenu par l'automatisation. Ne pas le régénérer à la main (.claude/rules/catalog-pr-hygiene.md).
3. Cocher les cases au fil des tranches — huit cases vides pour 48 PRs est le même défaut, en plus petit, que celui que cette passe corrige.

48 PRs mergées portent 3973. Zéro PR ouverte.

---

Corps d'origine conservé intégralement ci-dessous. La méthode ascendante, la partition lane-alignée et les contraintes HARD restent valides mot pour mot ; seules la section « État mesuré » du 30/08 et la lecture des cases avaient dérivé.

Contexte

L'Epic ascendant d'origine #1657 (« comprehensive README hierarchy refresh, bottom-up ») et ses 12 sous-issues familles (#1658-#1669, la dernière #1669 = root README « LAST ») sont CLOSED. La passe d'harmonisation #2651 et le refresh des comptes-en-dur dérivants #2572 sont également CLOSED.

Depuis, le dépôt a substantiellement évolué et les READMEs ont re-dérivé (comptes en dur obsolètes, contenu nouveau non décrit, descriptions périmées) :

• Preuves Lean : Bondareva-Shapley feat(lean): Bondareva-Shapley Core skeleton — isolate hyperplane-separation sorry #2959 désormais sorry-free (cap historique), Knot [EPIC] Knot Theory Lean — scaffolding, invariants, Conway knot & Piccirillo proof #2874 en cours, Conway [EPIC] Formalisations Lean : Conway (profondeur), Grothendieck, integration GameTheory + 3 exercices #2162.
• Libs : MetaGeneticSharp [EPIC] MetaGeneticSharp fork — embarque PR #87 + rebase upstream + submodule CoursIA + notebooks + release #1203 (fork étendu : compounds, embedding géométrique, GIF/colored-islands), Z3.Linq Epic: Fork Z3.Linq propre + reintegration EPFdevelopment + serie notebooks + PRs upstream #1206.
• Nouveaux notebooks + mise-en-forme [EPIC] Mise en forme visuelle des notebooks — verification de rendu + directives #3966 + axe-2 SOTA EPIC: axis-2 SOTA ledger -- every notebook PR-reviewed for proper SOTA-tool install/invocation (recoverable -> re-plug machine/env/user-hand) #3801.

Cet Epic resynchronise la hiérarchie README de bas en haut : on commence par les feuilles (READMEs de séries/sous-séries) et on remonte jusqu'au README principal. Il prolonge la directive permanente notebooks/READMEs <- dernières évolutions (preuves, libs, contenu).

Méthode (ASCENDANTE — feuilles d'abord, racine en DERNIER)

1. Feuilles : READMEs de séries/sous-séries (MyIA.AI.Notebooks/<famille>/.../README.md) — chacun resynchronisé sur l'état réel courant de ses notebooks/preuves/libs (liste à jour, descriptions fidèles, aucun compte en dur dérivant, références sources comme dans docs: rewrite README hierarchy with pedagogical content + source references #912).
2. Intermédiaires : READMEs de section/thème.
3. Racine (LAST) : MyIA.AI.Notebooks/README.md puis README.md repo — uniquement après que toutes les feuilles sont vertes.

Outillage : subagents readme-hierarchy-auditor (stratégie bottom-up) + readme-updater. Délégation Agent(model:"sonnet") pour l'audit/recensement read-heavy, jugement éditorial gardé par la lane.

Contraintes (HARD)

• Français d'abord (.claude/rules/readme-french-first.md) : prose nouvelle = FR ; bascule d'un README EN -> préserver l'original en README.en.md.
• Marqueurs CATALOG-STATUS INCHANGÉS (.claude/rules/catalog-pr-hygiene.md) : ne JAMAIS régénérer le catalogue sur une branche.
• 1 PR atomique par famille (G.4), See #THIS_EPIC (partiel, l'Epic reste OPEN ; root README = Closes final).
• Prose pédagogique (Objectifs / Conclusion / Navigation), pas de duplication, mettre à jour plutôt que créer (cf docs: passe d'harmonisation et d'enrichissement des READMEs (principal + sous-séries) #2651 template).

Partition lane-alignée (devient fallback pérenne des deep-queues)

Lane	Familles feuilles
po-2025:CoursIA	GenAI, ML, Probas, IIT, Search-Python, RL
po-2025:CoursIA-2	SymbolicAI non-Lean (Tweety/SemanticWeb/Planning/SmartContract), GameTheory non-Lean, Sudoku, CaseStudies
po-2024:CoursIA	QuantConnect
po-2024:CoursIA-2	MetaGeneticSharp (MGS)
po-2026:CoursIA	SymbolicAI/Lean séries (Conway, social_choice, Lean notebooks)
po-2026:CoursIA-2	Knot, Grothendieck, Lean math
ai-01 (LAST)	READMEs section/thème + racine MyIA.AI.Notebooks/README.md + README.md repo — APRÈS feuilles

Checklist ascendante

• Feuilles GenAI
• Feuilles QuantConnect
• Feuilles SymbolicAI (non-Lean) + Lean séries
• Feuilles Sudoku + Search + GameTheory + CaseStudies
• Feuilles ML + Probas + IIT + RL
• Feuilles MGS (Metaheuristics)
• Feuilles Knot / Grothendieck / Lean math
• (LAST) Section/thème READMEs + racine + README repo

Acceptance

• Chaque README feuille reflète l'état courant réel de ses notebooks/preuves/libs (pas de compte en dur dérivant ; nouveau contenu décrit).
• FR-first respecté, .en.md préservé si bascule.
• Marqueurs CATALOG-STATUS byte-identiques.
• Racine mise à jour en dernier, après toutes les feuilles.

État mesuré de la racine — 2026-08-30

L'audit Vibe confirme deux désynchronisations encore présentes sur origin/main :

• README.md annonce 1 024 notebooks (valeur datée du 17 août), tandis que COURSE_CATALOG.generated.md et le marqueur du hub MyIA.AI.Notebooks/README.md annoncent désormais 1 064 notebooks : écart +40. Le README racine ne porte aucun marqueur CATALOG-STATUS; le lien vers le catalogue ne rend donc pas son propre chiffre exact.
• README.md annonce 22 lakes Lean 4 à deux endroits. Le tree Git courant contient 28 fichiers lakefile.lean/lakefile.toml, dont un fixture tiers sous agent_tests/prover/session_state/reference_docs/; même en l'excluant conformément aux conventions du dépôt, le corpus propre compte 27 lakes, soit un écart +5 par rapport au README.

Chronologie vérifiée : le dernier commit touchant README.md est 0bbbfb40f (2026-08-23), tandis que le catalogue et le hub notebooks ont été régénérés par 82f0ca34f le 2026-08-29. Ces deux écarts sont donc des constats actuels, pas des lectures historiques déjà corrigées.

Statut : DÉRIVE CONFIRMÉE. La correction reste à porter dans la passe racine LAST, après les feuilles, conformément à la méthode de cet Epic; cette note ne prétend pas que l'acceptance globale est terminée.