Décisions (ADR)

Synthèse des ADR de conception. Statut d'origine : exploration — mais toutes prototypées et validées dans ce dépôt. Certaines concernent surtout le CLI grace ; c'est signalé.

ADR-1 · Un talent est compilé, jamais injecté tel quel

Injecter un talent en entier reproduit le problème du gros fichier de contexte. On distingue donc télécharger (installer la source) et injecter (ce qui atteint le LLM). Un compilateur (grace build, ou le resolver côté serveur ici) produit un artefact ciblé, avec deux sorties distinctes :

• A — doc lisible LLM (builder) ;
• B — config de validateur pour les talents enforceable (validator, en CI, jamais dans le LLM).

On ne gradue vers un mécanisme (Skill, MCP, hook) que sur preuve (si les prompt-tests montrent que le pull n'est pas fiable). Dans ce dépôt, c'est la sortie service : le resolver vit dans le backend, le MCP l'expose.

ADR-2 · Talents structurels = diagramme-as-code + contraintes vérifiables

• Diagramme-as-code, jamais image : Mermaid/DSL texte (lu par le LLM, diffable, indexable).
• Le vrai prix : un schéma structurel est machine-vérifiable → il sert builder et validator depuis une source unique (constraints.yml).
• Frontière : ça ne vaut que pour les talents structurels (couches, direction de dépendance). Le comportemental / décisionnel / lexical reste de la prose prescriptive + prompt-tests.
• Flag enforceable: true + le trio structure/model.md + structure/constraints.yml + conventions/<lang>.yml.

Implémenté ici : validate lit layers + dependency_rule typé avec sévérités, et génère la config CI. Voir Validation.

ADR-3 · MCP = voie de graduation du MVP fichiers

MCP n'est pas une alternative au MVP fichiers — c'est sa graduation. Même cœur (resolver), deux front-ends : grace build (offline, portable) et serveur MCP (online, dynamique). On déploie le MCP quand le catalogue est gros et/ou traité comme un produit (privé, auth, télémétrie).

• Pour : résolution dynamique server-side, recherche sur gros catalogue, zéro vendoring, télémétrie, auth privée.
• Contre : coût des schémas d'outils (→ surface ≤ ~5–6 outils), dépendance harness/runtime, pull non garanti, latence.

C'est l'ADR fondateur de ce dépôt : 6 outils MCP, boucle resolve → get → validate prouvée, dashboard partageant la même base.

ADR-4 · Modèle « gestionnaire de paquets » à 3 couches (surtout CLI)

Versioning des talents + « un outil LLM par développeur » = un système à 3 couches, par analogie npm/Cargo/Helm :

Réutiliser l'existant (semver + pubgrub), ne pas réécrire un résolveur maison. Concerne surtout le CLI grace ; ici, l'équivalent simplifié est ProjectTalent + ConfigRevision en base.