ADR-016 : Unification du modèle opt-in : concept unique, cycle install/enable à 4 verbes¶

Statut¶

Acceptée

Décision-cadre.
Les tickets d'exécution la référencent (« charte appliquée : ADR-016 »).

Contexte¶

Forge distribue six briques optionnelles (forge-mvc-mfa, forge-mvc-rbac, forge-mvc-workflow, forge-mvc-stats, forge-mvc-media, forge-mvc-iot) en plus du noyau minimal.
L'expérience de ces briques souffre aujourd'hui de trois incohérences accumulées au fil des versions :

1. Trois mots pour un même référent¶

Une même chose, une brique optionnelle, est nommée de trois façons selon l'endroit :

module : « modules officiels » (CLAUDE.md §1, ADR-005) ;
package : la distribution PyPI (forge-mvc-iot) ;
opt-in : « opt-ins officiels » (docs d'installation).

Pire, deux de ces mots sont doublement chargés : « module » désigne aussi le système local modules/ (module:install / module:remove, module.json) et « opt-in » désigne aussi la couche de câblage optins/ (register_optins).

2. Trois mécanismes de branchement hétérogènes¶

Les briques n'ont pas la même surface de contact avec une application :

possède des routes (iot) → expose register_iot_routes(router), se branche via la couche optins/ ;
bibliothèque pure (workflow, stats, media) → on importe et on appelle ses fonctions ; rien à brancher ;
transversale (mfa, rbac) → se greffe dans un flux existant (mfa_available() dans le squelette, décorateurs pour RBAC).

Conséquence visible : optin:enable ne supporte que iot, et forge_mvc_rbac s'auto-enregistre à l'import (un provider de contexte Jinja), ce qui contredit le principe §3 « refuser la magie cachée ».

3. Install / désinstall asymétriques¶

le système modules/ local a module:install et module:remove (symétriques, retrait de bloc par marqueurs) ;
le système optins/ a optin:enable mais pas optin:disable ;
starter:build injecte des routes mais n'a pas de retrait.

Le retrait propre existe donc côté « module » mais pas côté « opt-in ».

4. Squelette non neutre¶

mvc/routes.py livre par défaut des routes pré-câblées (auth, MFA conditionnel, starter welcome).
Un développeur qui clone le dépôt ou installe via pipx n'obtient pas un squelette vierge : des capacités sont déjà branchées sans geste explicite de sa part.

Fenêtre temporelle¶

Forge est en bêta publique pré-1.0.
La convention (CLAUDE.md §2) autorise les ruptures internes sans alias dépréciés avant le tag 1.0 stable.
C'est la fenêtre idéale pour unifier sans dette de compatibilité.

Décision¶

D1 : « opt-in » est le concept unique¶

« opt-in » devient le seul terme désignant une brique optionnelle.
Le mot « module officiel » est retiré de la documentation, des ADR et des messages CLI.
« package » est conservé uniquement comme véhicule de distribution (« un opt-in officiel est livré comme un package PyPI »).

Le mot « module » reste disponible pour le seul système local (code que le développeur écrit lui-même), désormais traité comme un opt-in de source locale, sans recouvrement avec les briques officielles.

D2 : Deux axes orthogonaux, quatre verbes¶

Le cycle de vie d'un opt-in se décompose en deux axes indépendants :

présence (le code est-il sur la machine ?) → install / remove ;
activation (est-il branché dans l'app ?) → enable / disable.

                 install              enable
   absent  ───────────────▶  installé  ───────────────▶  activé
           ◀───────────────           ◀───────────────
                 remove               disable

Commande	Axe	Source officielle	Source locale
`forge opt-in:install <x>`	présence +	`pip install` / `pipx inject`	scaffold `optins/<x>/`
`forge opt-in:enable <x>`	activation +	câblage + `register_optins`	injection de marqueurs dans `mvc/routes.py`
`forge opt-in:disable <x>`	activation −	retrait des marqueurs (laisse installé)	idem
`forge opt-in:remove <x>`	présence −	`pip uninstall` / `pipx uninject`	suppression de `optins/<x>/` (gardée, voir D6)
`forge opt-in:list`	lecture	source + état (`absent` / `installé` / `activé`)	idem

D3 : Garanties par construction¶

install n'active jamais automatiquement (§3 « refuser la magie cachée » garanti par le découpage) ;
disable ne désinstalle jamais (débranchement réversible sans perte de code).

D4 : Emplacement unique des opt-ins activés¶

Tout opt-in activé vit sous optins/<name>/, quelle que soit sa source.
Le dossier contient deux natures de fichiers selon la source :

officiel → câblage mince généré (régénérable, write-if-new) ;
local → code utilisateur (protégé §9, hook forge-write-if-new.sh).

D5 : Fusion des moteurs et rupture CLI¶

Les deux moteurs module:* et optin:* fusionnent en une seule famille opt-in:*.
Les anciennes commandes (module:install, module:remove, module:files, module:routes, optin:enable, optin:list) sont supprimées franchement, sans alias déprécié (fenêtre pré-1.0).
Le moteur de retrait par marqueurs existant (module:remove, route_ops) est réutilisé pour opt-in:disable.

D6 : `remove` sur source locale est une opération gardée¶

opt-in:remove sur une source officielle se borne à désinstaller le package : aucun fichier utilisateur touché.
Sur une source locale, il supprimerait du code écrit par le développeur ; il est donc :

non destructif par défaut : affiche ce qui serait supprimé (--dry-run implicite, convention Forge) ;
destructif seulement avec --force + confirmation explicite ;
aligné sur le hook forge-write-if-new.sh (le CLI ne le contourne pas).

D7 : Squelette neutre¶

mvc/routes.py livré par défaut ne contient qu'une route :

from core.http.router import Router
from mvc.controllers.home_controller import HomeController

router = Router()

with router.group("", public=True) as public:
    public.add("GET", "/", HomeController.index, name="home")

Auth, MFA et le starter welcome ne sont plus pré-câblés : ils s'ajoutent par opt-in:* (auth/MFA) ou starter:build (welcome).

D8 : Adaptateur trois-formes¶

Derrière l'interface uniforme opt-in:*, un adaptateur résout la forme de chaque opt-in (monter des routes / greffer des contrôleurs / pure bibliothèque / copie de fichiers locaux).
L'uniformité vit au niveau du contrat, pas de l'implémentation ; l'utilisateur ne voit jamais la différence.

D9 : Les starters restent hors périmètre¶

Un starter est une démo pédagogique, pas une capacité optionnelle.
Les commandes starter:* restent distinctes de opt-in:*.

Conséquences¶

Rupture CLI assumée : les commandes module:* et optin:* disparaissent au profit de opt-in:*.
Acceptable en pré-1.0 (CLAUDE.md §2).
Renommage transverse : « module officiel » → « opt-in » dans CLAUDE.md, ADR-005, docs d'installation, textes d'aide.
Migration des tests : les meta-tests qui épinglent l'ancien vocabulaire, les anciennes commandes ou les blocs du squelette (test_app_default_no_mfa_001, test_module_remove_001, etc.) doivent être ajustés ou redéployés.
Correctif §3 : l'auto-enregistrement Jinja de forge_mvc_rbac à l'import doit redevenir explicite (sinon une brique se branche dans le dos de l'utilisateur, en contradiction avec D3).
Réversibilité acquise : tout opt-in devient désactivable proprement, ce qui n'était vrai que pour les modules locaux.
Découpage en tickets : vocabulaire → squelette neutre → CLI unifié → adaptateur + source locale → migration des tests (un ticket = une responsabilité, §5).

Alternatives considérées¶

Garder « module » comme mot canonique.
Plus familier, mais « module » est déjà pris par le système local et par « module officiel » ; le mot ne porte pas la philosophie du choix explicite.
Écarté au profit d'« opt-in », terme déjà présent dans la doc et porteur du principe §8.

Conserver les deux moteurs séparés (module:* et optin:*).
Maintient la duplication et l'asymétrie de retrait.
Écarté : la valeur recherchée est précisément une surface unique pour l'utilisateur.

Un seul verbe remove --purge plutôt que quatre verbes.
Mélange les axes présence et activation dans une seule commande paramétrée.
Écarté : séparer install/remove (présence) de enable/disable (activation) rend les états explicites et garantit « install n'active pas » / « disable ne désinstalle pas » par construction.

Uniformiser aussi l'implémentation du branchement.
Forcerait une cérémonie register_optins vide sur les bibliothèques pures (stats, workflow, media).
Écarté : l'uniformité doit vivre au niveau du contrat (D8), pas des mécanismes internes.

Inclure les starters dans le modèle opt-in.
Les starters injectent aussi des routes, mais ce sont des démos pédagogiques, pas des capacités.
Les fusionner brouillerait les deux intentions.
Écarté (D9).

Amendements¶

A1 : Câblage opt-in : pattern registre, pas marqueurs (palier 3b)¶

D2/D4 décrivaient opt-in:enable comme « injection marqueurs + register_optins ».
L'implémentation (palier 3b) a révélé que la couche optins/ existante utilise uniquement le pattern registre : un seul point d'injection dans mvc/routes.py (register_optins(router)) qui délègue à optins/registry.py, puis à chaque opt-in.
C'est un design plus propre que des marqueurs par opt-in (un seul appel dans routes.py, aucun bloc par brique) et optin:enable --apply l'auto-injecte déjà.

Décision retenue : conserver le pattern registre pour le câblage des opt-ins.
Les marqueurs # forge-starter:<id> restent réservés aux starters et aux modules locaux (qui injectent un bloc de routes).
opt-in:enable n'utilise pas de marqueurs ; opt-in:disable est l'inverse exact d'enable (retire la couche optins/<name>/ et l'appel register_optins si plus aucun opt-in actif).

opt-in:enable/disable restent limités à iot jusqu'à l'adaptateur 3-formes (ticket 4), qui généralise le câblage aux six opt-ins.

A2 : Le système `module:*` local reste distinct (ticket 4b)¶

D5 prévoyait de fusionner les moteurs module:* et optin:*.
L'implémentation (palier 4b) a révélé que le système de module local a un cycle de vie d'auteur fondamentalement différent du modèle opt-in à 4 verbes :

module:install, déclare le module dans forge_modules.json ;
module:files, copie les fichiers dans l'application ;
module:routes, génère un fichier mvc/routes_<module>.py séparé à copier (« Forge affiche », ne touche jamais mvc/routes.py) ;
module:remove, retire ce que Forge peut prouver avoir installé.

Ce déclarer → copier → générer-des-routes (on fabrique sa brique) ne mappe pas 1:1 sur install affiche / enable câble / disable débranche (on consomme une brique officielle).
Forcer la fusion reviendrait à redéfinir un sous-système testé et à migrer ~40 tests pour un seul nom de commande unifié.

Décision retenue : ne pas fusionner.
Le système module:* reste l'outil du workflow d'auteur de module local ; la famille opt-in:* couvre les opt-ins officiels (catalogue cli/optins/catalog.py).
Conceptuellement, un module local est un « opt-in de source locale » (vocabulaire unifié, glossaire), mais il garde ses commandes propres car son cycle de vie diffère.
Quand un nom inconnu est passé à opt-in:*, la commande oriente vers forge module:install.

Cet amendement clôt la trajectoire ADR-016 : la surface opt-in officielle est unifiée (install/remove/enable/disable/list), kind-aware, sans commandes legacy.

Liens¶

Charte : principes §3 (magie cachée), §8 (noyau minimal, briques opt-in), §9 (pas d'écriture invisible), §11 (une seule façon officielle).
ADR-004, périmètre du core minimal.
ADR-005, packaging monorepo + distributions PyPI.
ADR-012, politique de dépréciation (cadre pour la rupture pré-1.0 sans alias).