ADR-035 : Modèle pédagogique unique : parcours réalisés à la main, retrait de la génération¶

Statut¶

Accepté, Forge 1.0.0-beta.16 (ticket ADR-STARTERS-MANUAL-001).

Supersède l'ADR-023 (forge starter:build comme façon canonique de construire un
starter) et clôt le volet starter:build laissé ouvert par l'ADR-030.
Généralise à tous les parcours opt-in le modèle déjà retenu pour welcome-forge
par les ADR-025 et ADR-028 (tutoriel manuel).

Aucune suppression de code n'est appliquée avant que le pré-requis anti-casse
(migration de la documentation) ne soit terminé : la décision est actée, le
démontage est séquencé après la migration.

Date¶

2026-06-16

Contexte¶

Forge propose deux mécanismes pédagogiques contradictoires pour la même
collection de parcours :

Le parcours de base welcome-forge est un tutoriel manuel (ADR-025,
ADR-028) : chaque palier de doc montre le fichier complet à créer (contrôleur,
vue) et la ligne exacte à ajouter dans mvc/routes.py. L'apprenant tape et lit
le code, le câblage est un geste explicite.
Les parcours opt-in (welcome-mail, welcome-iot, welcome-images,
welcome-files, welcome-audio, welcome-mfa, welcome-rbac,
welcome-workflow, welcome-stats, welcome-video) sont générés par
forge starter:build <id> (ADR-023) : la commande pose les fichiers et
injecte les routes dans mvc/routes.py via des marqueurs
# forge-starter:<nom>:start / :end.

Cette dualité pose trois problèmes :

Écriture dans le code utilisateur. starter:build réécrit
mvc/routes.py, ce que la charte protège le plus fortement (principe 9, mode
§7 « Forge ne réécrit jamais silencieusement un fichier applicatif »).
L'injection de routes est déjà une source de régressions connue (audit
beta.14 : « la détection du router corrompt routes.py »), et l'ADR-030 a dû
être ouvert pour tenter de réconcilier ce comportement avec la règle 4.3.
Incohérence pédagogique (principe 11). Deux façons officielles de suivre
un parcours selon qu'il est de base ou opt-in. La charte impose une seule
façon officielle de faire chaque chose.
Coût de maintenance. Le sous-système de génération représente
~4 900 lignes de code, 419 fichiers de données embarqués et ~19 000 lignes de
tests, pour un framework dont l'identité est « noyau minimal, explicite,
pédagogique, durable ». Si chaque palier dispose d'une page de documentation,
le générateur fait largement doublon avec le mode « Forge affiche ».

Sur le fond pédagogique, « l'application tourne sans rien lire » est un
anti-objectif pour un framework d'apprentissage : générer invite à sauter la
lecture, alors que recopier oblige à lire chaque ligne.

Décision¶

Forge adopte un modèle pédagogique unique pour tous les parcours : ils sont
réalisés à la main par l'apprenant en suivant la documentation, sur le modèle
de welcome-forge. La génération de starters est retirée.

Concrètement :

La commande forge starter:build est supprimée.
La commande forge starter:list et le registre starter.json sont supprimés :
sans génération, le registre n'a plus d'objet. Les parcours se découvrent par
la navigation de la documentation.
Le sous-système de génération est retiré : cli/starters/builder.py,
route_ops.py, scaffold.py, le registre, ainsi que l'arborescence de données
cli/starters/data/.
L'injection de routes dans mvc/routes.py par une commande Forge disparaît
pour les starters. Le câblage des routes redevient un geste manuel décrit dans
la documentation.

Chaque palier de documentation devient autosuffisant : il indique les
fichiers à créer (contrôleur, vue, et le cas échéant modèle / migration) et la
ligne de route à ajouter dans mvc/routes.py, exactement comme welcome-forge.

Pré-requis anti-casse : migration de la documentation d'abord¶

Le code de référence des parcours opt-in n'existe aujourd'hui que dans
cli/starters/data/ ; il est posé par build. Aucune suppression n'a
lieu avant que la documentation ne soit autosuffisante. L'ordre est :

Rapatrier dans les pages de doc le code manquant, depuis data/ :
- welcome-mail (6 paliers) : aujourd'hui sans aucun code dans la doc, à
compléter entièrement (contrôleur, vue, route).
- les 9 autres parcours : le code des contrôleurs et vues est déjà présent,
mais le câblage des routes manque à la quasi-totalité des paliers (il
était injecté par build). Ajouter à chaque palier la section « Route »
façon welcome-forge.
Vérifier chaque parcours de bout en bout : un lecteur doit pouvoir le
réaliser à la main sans starter:build.
Démonter seulement ensuite le sous-système de génération et nettoyer les
tests de génération et les références documentaires (docs/reference/,
docs/release/, schémas).

Conséquences¶

Positives :

Une seule façon officielle de suivre un parcours (principe 11).
Plus aucune écriture Forge dans mvc/routes.py côté starters (principes 3, 9 ;
ferme le volet starter:build de l'ADR-030).
Réduction majeure de la surface de maintenance (code, données, tests).
Pédagogie homogène : l'apprenant lit et écrit chaque ligne.

Négatives / coûts :

Effort de migration documentaire (un parcours mail à écrire, ~75 paliers à
compléter d'une section « Route »).
Perte du confort « projet qui tourne immédiatement » ; assumé comme cohérent
avec un framework d'apprentissage.
forge starter:list / starter:build disparaissent de la CLI ; les
références (aide, docs/reference/cli-commands.md, api.md,
stability-contract.md, schémas) sont à nettoyer.

ADR liés¶

Supersède l'ADR-023 (starter:build canonique, forge new nu) : le volet
starter:build est annulé ; la partie « forge new produit un projet nu »
reste valable.
Clôt le volet starter:build de l'ADR-030 : la question de l'injection de
routes par starter:build devient sans objet (la commande disparaît). Le volet
make:public-* de l'ADR-030 reste à traiter séparément.
Généralise les ADR-025 et ADR-028 (modèle manuel de welcome-forge) à tous
les parcours.

Charte appliquée¶

Principe 3, refuser la magie cachée (plus d'injection de routes).
Principe 9, pas d'écriture invisible dans le code utilisateur (mvc/routes.py
n'est plus réécrit par Forge pour les starters).
Principe 11, une seule façon officielle de faire chaque chose (modèle manuel
unique).
Règle A, retirer la cause (la génération), pas le symptôme (les bugs
d'injection de routes).
Note pré-1.0, en phase bêta, le retrait se fait sans alias déprécié ni guide
de migration externe.