designwithai-mcp 0.5.0 → 0.10.0

package/README.md

@@ -107,11 +107,19 @@ règles, anti-patterns, prompts, checklists, scorecards), en lecture.
 | `clear_gate` / `reopen_gate` / `gate_status` | Boucle d'état des gates (ferme un gate avec preuve) | `clear_gate` **refuse sans artefact** |
 | `audit_project` | Flow bout-en-bout : orchestrateur + profil + ancrage cité + traçage | **Refuse sans artefact** |
 | `list_eval_cases` / `get_eval_case` / `score_review` / `skill_scorecard` | Banc d'éval : prouve la qualité d'un skill (détection, périmètre, refus) | golden jamais révélée (run aveugle) |
-| `verify_fix` | Vérifie qu'une reco a été appliquée, critère par critère | **Refuse sans artefact/critères** |
+| `verify_fix` | Vérifie qu'une reco a été appliquée, critère par critère — sur l'élément POINTÉ quand le constat porte une coordonnée | **Refuse sans artefact/critères** ; « élément non retrouvé » n'est JAMAIS « corrigé » |
 | `generate_decision_record` | Décision traçable (ADR) persistée | — |
 | `push_audit` | Envoie une review vers le compte designwithai (cockpit multi-appareils) | **Refuse sans `DWAI_TOKEN`** ; jeton révocable, jamais de clé forte |
 | `next_gate` | Prochain gate conscient des PRÉRÉQUIS (graphe) | ne propose que les gates débloqués |
 | `connect_repo` | Lit un dépôt local (stack, composants, tokens, sources) | distant = via les MCP dédiés |
+| `inventory_ds` | Inventorie le design system d'un dépôt — valeurs, composants, états déclarés — et range DEUX faces : le code et ses fiches | lecture déterministe ; ce qui n'est pas compris est nommé, jamais deviné |
+| `submit_inventory` | Reçoit un inventaire produit ailleurs (maquette Figma, fiches) au format commun | **refuse motivé** ; un inventaire partiel sans liste de ce qui n'a pas été lu est rejeté |
+| `declare_source_of_truth` | Déclare qui fait foi, couche par couche (valeurs / états / rendu) | ne devine JAMAIS une source ; propose l'ADR, ne l'écrit pas |
+| `diff_inventories` | Compare les trois faces : ce qui diverge, ce qui manque, et dans quel sens | une absence n'est un constat que si la face d'en face est lue entièrement |
+| `save_framing` | Écrit un dossier de cadrage dans le projet, au format que `framing_criteria` relit | refuse la FORME, jamais le contenu ; le **verdict** ne s'y pose qu'après passage devant le juge |
+| `list_framings` | Les cadrages du projet et leur verdict — ou son absence, dite telle quelle | `judged_only` ne rend que ceux qui ont passé leur juge |
+| `submit_annotations` | Reçoit un lot d'éléments POINTÉS dans une app qui tourne (route, sélecteur, note) | normaliseur tolérant ; ce qui n'est pas compris est GARDÉ, ce qui n'est pas rangeable est NOMMÉ |
+| `framing_criteria` *(étendu)* | Les critères d'acceptation à vérifier, **projet d'abord**, compte ensuite | la source lue est nommée ; un dossier jamais jugé le dit |
 
 **Recherche sémantique** (optionnelle, sans clé) : `npm run embed` pré-calcule des embeddings locaux (modèle multilingue, ONNX) → `handbook-embeddings.json`. Présent, `search_handbook` devient hybride (mots-clés + sens) ; absent, il retombe sur les mots-clés seuls. À relancer après chaque régénération de `handbook.json`.
 
@@ -120,6 +128,74 @@ Le profil est chargé au démarrage depuis `.designwithai/profile.json` (ou `DWA
 Tous acceptent `delivery_mode` (`ai-builder` / `classique` / `hybride`) et
 filtrent comme le fait le site.
 
+### L'arbitre à trois faces
+
+Le design system existe en trois exemplaires qui se contredisent : la maquette,
+le code, les fiches de composant. Ce serveur ne se connecte à aucun des trois —
+il REÇOIT des inventaires et rend des jugements. Aucun secret n'y transite.
+
+Un seul format normalisé pour les trois faces (`src/inventory-schema.ts`), et une
+règle qui commande tout le reste : **un inventaire qui se déclare partiel sans
+dire ce qu'il n'a pas lu est refusé à l'entrée.** Sans cette liste, « absent du
+code » et « pas su lire » deviennent indiscernables, et le comparateur se met à
+produire des fautes qui n'existent pas.
+
+Dans l'ordre : `inventory_ds` (code + fiches) → `submit_inventory` (maquette,
+depuis le MCP Figma) → `declare_source_of_truth` (facultatif) →
+`diff_inventories`. Sans déclaration, la comparaison reste symétrique et le dit ;
+avec, elle oriente — « le code s'est éloigné de la maquette sur 7 valeurs de
+style » plutôt que « 7 divergences ».
+
+Les inventaires sont rangés dans `.designwithai/inventories/` (surchargeable par
+`DWAI_INVENTORIES_PATH`), les déclarations dans `.designwithai/source-of-truth.json`
+(`DWAI_TRUTH_PATH`).
+
+### La chaîne d'une feature, dans l'éditeur
+
+Le PM dit « j'ai une idée » et la chaîne l'emmène : cadrage jugé → impact chiffré
+→ prototype dans le vrai design system → protocole de test → synthèse confrontée
+aux critères → décision tracée.
+
+Trois skills **produisent**, et c'est là qu'est la discipline : **la sortie d'un
+producteur est soumise à son juge avant d'être inscrite au registre.** Un skill
+qui génère puis s'admire produit du texte plausible — c'est ce que le prompt
+gratuit fait déjà. La règle est écrite dans `skills/_shared/producteurs.md`.
+
+| Producteur | Juge apparié |
+|---|---|
+| `frame-feature` | `review-feature-framing` |
+| `prototype-feature` | `better-states` + `better-interface` |
+| `prepare-user-test` | *(aucun — sa grille de refus et son corpus le tiennent)* |
+
+`synthesize-user-feedback` n'est pas un producteur : c'est le juge des notes de
+test, qui les confronte aux critères du cadrage.
+
+Les cadrages vivent dans `.designwithai/framings/` (`DWAI_FRAMINGS_PATH`), les
+prototypes dans `.designwithai/prototypes/`.
+
+### Le pointage — juger sur des coordonnées
+
+On ne construit pas d'outil d'annotation : d'autres le font (Agentation,
+sv-agentation…). On définit ce qu'on sait en RECEVOIR — route, sélecteur, note —
+comme pour les inventaires Figma et Storybook.
+
+Trois gains, et le troisième est le moins évident :
+
+1. un juge travaille sur une **coordonnée** au lieu d'une description ;
+2. deux passes s'apparient dessus : « ton produit monte » cesse de dépendre de
+   la prose d'un modèle ;
+3. `verify_fix` va regarder **cet** élément, sur **cette** route.
+
+**Et la règle qui protège tout le reste :** un sélecteur qu'on ne retrouve plus
+n'est pas un défaut corrigé. Un renommage de classe CSS ferait sinon passer tous
+les constats ancrés en « réglé » — le rapport le plus faux et le plus crédible
+que ce produit puisse rendre. La garantie est un calcul (`verify-target.ts`),
+pas une intention, et `diffFindings` range ces cas dans `deplaces` : ni réglés,
+ni nouveaux.
+
+Les lots vivent dans `.designwithai/annotations/` (`DWAI_ANNOTATIONS_PATH`).
+Un constat sans ancre suit exactement le chemin d'avant.
+
 **Prompts** — les 10 skills de `skills/` exposés comme prompts MCP (`/better-layout`,
 `/better-interface`, `/review-ai-product`…). Chaque prompt est *self-contained* :
 socle commun + corps du skill + invocation renseignée par les arguments

package/dist/annotation-schema.js

@@ -0,0 +1,277 @@
+/**
+ * L'ANNOTATION — ce qu'on sait recevoir quand quelqu'un pointe un élément.
+ *
+ * On ne construit pas d'outil d'annotation. D'autres le font déjà — on clique
+ * un élément d'une application qui tourne, et on obtient un bloc structuré :
+ * la route, un sélecteur, une note. Ce fichier définit ce qu'on sait en faire,
+ * exactement comme `inventory-schema.ts` définit ce qu'on sait recevoir d'un
+ * inventaire Figma sans jamais ouvrir Figma.
+ *
+ * CE QUE ÇA CHANGE, ET C'EST TRIPLE :
+ *   — un juge travaille sur des COORDONNÉES au lieu d'une description ;
+ *   — deux passes s'apparient sur ces coordonnées, ce qui rend « ton produit
+ *     monte » beaucoup moins dépendant de la prose d'un modèle ;
+ *   — `verify_fix` va regarder CET élément-là, et pas « la page ».
+ *
+ * LE NORMALISEUR EST TOLÉRANT, ET C'EST DÉLIBÉRÉ. Chaque outil a sa forme —
+ * `url` ici, `route` là, `comment` d'un côté, `note` de l'autre. On extrait ce
+ * qu'on reconnaît, et **on garde tel quel ce qu'on ne comprend pas** dans
+ * `brut`. Jeter un champ inconnu, c'est perdre en silence une information que
+ * quelqu'un avait pris la peine de produire ; la garder sans l'interpréter ne
+ * coûte rien et laisse la porte ouverte.
+ *
+ * Aucune dépendance : ce module peut partir dans un bundle navigateur.
+ */
+export const ORIGINES = ["outil", "collage"];
+/**
+ * Un plafond, pour que le refus soit un refus et pas un plantage.
+ *
+ * Cinq cents éléments pointés ne sont pas une session d'annotation : c'est un
+ * export accidentel. Le dire coûte moins cher que de le persister.
+ */
+export const MAX_ANNOTATIONS = 500;
+const estObjet = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const chaine = (v) => typeof v === "string" && v.trim().length > 0;
+/**
+ * Valide un lot, strictement, et MOTIVE son refus.
+ *
+ * Les trois champs obligatoires d'une annotation sont ceux sans lesquels elle ne
+ * sert à rien : sans route ni sélecteur, on ne sait pas où regarder ; sans note,
+ * on ne sait pas quoi regarder. Tout le reste est facultatif — y compris la
+ * capture, qui n'est jamais qu'un confort.
+ */
+export function validerLot(brut) {
+    const erreurs = [];
+    if (!estObjet(brut))
+        return { ok: false, erreurs: ["Le lot doit être un objet."] };
+    const origine = brut.origine;
+    if (!chaine(origine) || !ORIGINES.includes(origine)) {
+        erreurs.push(`origine doit valoir ${ORIGINES.map((o) => `« ${o} »`).join(" ou ")}.`);
+    }
+    const annotations = [];
+    if (!Array.isArray(brut.annotations)) {
+        erreurs.push("annotations doit être une liste — une entrée par élément pointé.");
+    }
+    else if (brut.annotations.length === 0) {
+        erreurs.push("Le lot est vide : rien n'a été pointé, il n'y a rien à ranger.");
+    }
+    else if (brut.annotations.length > MAX_ANNOTATIONS) {
+        erreurs.push(`${brut.annotations.length} annotations : au-delà de ${MAX_ANNOTATIONS}, ce n'est plus une ` +
+            "session de pointage mais un export accidentel.");
+    }
+    else {
+        brut.annotations.forEach((a, i) => {
+            const ou = `annotations[${i}]`;
+            if (!estObjet(a)) {
+                erreurs.push(`${ou} doit être un objet.`);
+                return;
+            }
+            if (!chaine(a.route))
+                erreurs.push(`${ou}.route est obligatoire — sans elle, on ne sait pas sur quel écran regarder.`);
+            if (!chaine(a.selector))
+                erreurs.push(`${ou}.selector est obligatoire — sans lui, on ne sait pas quel élément regarder.`);
+            if (!chaine(a.note))
+                erreurs.push(`${ou}.note est obligatoire — un élément pointé sans rien à en dire n'est pas une annotation.`);
+            for (const cle of ["texte", "capture"]) {
+                if (a[cle] !== undefined && typeof a[cle] !== "string")
+                    erreurs.push(`${ou}.${cle} doit être un texte.`);
+            }
+            if (a.dimensions !== undefined) {
+                const d = a.dimensions;
+                if (!estObjet(d) || typeof d.largeur !== "number" || typeof d.hauteur !== "number") {
+                    erreurs.push(`${ou}.dimensions doit valoir { largeur, hauteur } en nombres.`);
+                }
+            }
+            if (a.brut !== undefined && !estObjet(a.brut))
+                erreurs.push(`${ou}.brut doit être un objet.`);
+            if (chaine(a.route) && chaine(a.selector) && chaine(a.note)) {
+                annotations.push({
+                    route: a.route.trim(),
+                    selector: a.selector.trim(),
+                    note: a.note.trim(),
+                    ...(chaine(a.texte) ? { texte: a.texte.trim() } : {}),
+                    ...(chaine(a.capture) ? { capture: a.capture.trim() } : {}),
+                    ...(estObjet(a.dimensions) &&
+                        typeof a.dimensions.largeur === "number" &&
+                        typeof a.dimensions.hauteur === "number"
+                        ? { dimensions: { largeur: a.dimensions.largeur, hauteur: a.dimensions.hauteur } }
+                        : {}),
+                    ...(estObjet(a.brut) && Object.keys(a.brut).length > 0 ? { brut: a.brut } : {}),
+                });
+            }
+        });
+    }
+    if (erreurs.length > 0)
+        return { ok: false, erreurs };
+    return {
+        ok: true,
+        lot: {
+            at: chaine(brut.at) ? brut.at : "",
+            origine: origine,
+            ...(chaine(brut.outil) ? { outil: brut.outil.trim() } : {}),
+            ...(chaine(brut.product_ref) ? { product_ref: brut.product_ref.trim() } : {}),
+            annotations,
+        },
+    };
+}
+/* ─── Le normaliseur, tolérant ───────────────────────────────────────────── */
+/**
+ * LES NOMS QU'ON RECONNAÎT, par ordre de préférence.
+ *
+ * La liste est courte et EXPLICITE : chaque entrée est une équivalence qu'on
+ * assume. Elle ne devine pas — un champ absent de cette table part dans `brut`,
+ * intact. Allonger la liste demande d'avoir vu un outil qui l'emploie.
+ */
+export const ALIAS = {
+    route: ["route", "path", "pathname", "url", "page", "screen", "ecran"],
+    selector: ["selector", "cssSelector", "css", "xpath", "domSelector", "target", "element_selector"],
+    note: ["note", "comment", "commentaire", "message", "feedback", "remark", "description"],
+    texte: ["texte", "text", "textContent", "innerText", "elementText", "label"],
+    capture: ["capture", "screenshot", "screenshot_description", "image_description"],
+};
+const NORMALISES = new Set([
+    ...ALIAS.route, ...ALIAS.selector, ...ALIAS.note, ...ALIAS.texte, ...ALIAS.capture,
+    "dimensions", "rect", "size", "brut", "boundingRect",
+]);
+function premier(o, cles) {
+    for (const c of cles) {
+        const v = o[c];
+        if (typeof v === "string" && v.trim().length > 0)
+            return v.trim();
+    }
+    return undefined;
+}
+/**
+ * UNE URL DEVIENT UNE ROUTE.
+ *
+ * Les outils livrent souvent `http://localhost:3000/rapport?tab=2#haut`. Ce qui
+ * identifie l'écran, c'est `/rapport` — le port change entre deux machines, la
+ * requête et l'ancre changent entre deux clics, et un appariement sur l'URL
+ * entière ne survivrait pas au premier changement d'environnement.
+ *
+ * Ce qui n'est pas une URL est rendu tel quel : une route est déjà une route.
+ */
+export function routeDepuis(v) {
+    const t = v.trim();
+    const m = t.match(/^[a-z][a-z0-9+.-]*:\/\/[^/]+(\/[^?#]*)?/i);
+    if (m)
+        return m[1] && m[1].length > 0 ? m[1] : "/";
+    return t.split("?")[0].split("#")[0] || t;
+}
+function dimensionsDepuis(o) {
+    for (const cle of ["dimensions", "rect", "size", "boundingRect"]) {
+        const d = o[cle];
+        if (!estObjet(d))
+            continue;
+        const l = d.largeur ?? d.width ?? d.w;
+        const h = d.hauteur ?? d.height ?? d.h;
+        if (typeof l === "number" && typeof h === "number")
+            return { largeur: l, hauteur: h };
+    }
+    return undefined;
+}
+/**
+ * Normalise UNE entrée venue d'un outil quelconque.
+ *
+ * Deux niveaux : les champs de premier rang, puis ceux d'un objet `element` ou
+ * `target` imbriqué — la forme la plus répandue. Ce qui reste part dans `brut`,
+ * SANS être interprété.
+ */
+export function normaliserAnnotation(brut) {
+    if (!estObjet(brut))
+        return null;
+    const imbrique = [brut.element, brut.target, brut.node].find(estObjet) ?? {};
+    const cherche = (cles) => premier(brut, cles) ?? premier(imbrique, cles);
+    const routeBrute = cherche(ALIAS.route);
+    const selector = cherche(ALIAS.selector);
+    const note = premier(brut, ALIAS.note);
+    if (!routeBrute || !selector || !note)
+        return null;
+    /* Le texte de l'élément ne doit JAMAIS être confondu avec la note : un `text`
+       de premier rang est ambigu, on ne le prend que s'il n'a pas déjà servi de
+       note, et on préfère toujours celui de l'objet imbriqué. */
+    const texte = premier(imbrique, ALIAS.texte) ?? (premier(brut, ALIAS.note) === premier(brut, ALIAS.texte) ? undefined : premier(brut, ALIAS.texte));
+    const restes = {};
+    for (const source of [brut, imbrique]) {
+        for (const [k, v] of Object.entries(source)) {
+            if (NORMALISES.has(k) || k === "element" || k === "target" || k === "node")
+                continue;
+            if (v === undefined || v === null)
+                continue;
+            restes[k] = v;
+        }
+    }
+    const dims = dimensionsDepuis(brut) ?? dimensionsDepuis(imbrique);
+    return {
+        route: routeDepuis(routeBrute),
+        selector,
+        note,
+        ...(texte ? { texte } : {}),
+        ...(cherche(ALIAS.capture) ? { capture: cherche(ALIAS.capture) } : {}),
+        ...(dims ? { dimensions: dims } : {}),
+        ...(Object.keys(restes).length > 0 ? { brut: restes } : {}),
+    };
+}
+/**
+ * Normalise un lot entier.
+ *
+ * Ce qui n'a pas pu être normalisé est NOMMÉ, pas jeté en silence. Une entrée
+ * sans sélecteur n'est pas une annotation — mais la personne qui l'a collée
+ * doit l'apprendre, sinon elle croira que ses cinq pointages sont rangés alors
+ * qu'il n'y en a que quatre.
+ */
+export function normaliserLot(entrees, opts = {}) {
+    const annotations = [];
+    const ignorees = [];
+    entrees.forEach((e, i) => {
+        const a = normaliserAnnotation(e);
+        if (a) {
+            annotations.push(a);
+            return;
+        }
+        const o = estObjet(e) ? e : {};
+        const manque = [
+            premier(o, ALIAS.route) ? null : "route",
+            premier(o, ALIAS.selector) ? null : "sélecteur",
+            premier(o, ALIAS.note) ? null : "note",
+        ].filter(Boolean);
+        ignorees.push(`entrée ${i + 1} : ${manque.length ? `il manque ${manque.join(", ")}` : "forme non reconnue"}.`);
+    });
+    return {
+        lot: {
+            at: opts.at ?? "",
+            origine: opts.origine ?? "collage",
+            ...(opts.outil ? { outil: opts.outil } : {}),
+            ...(opts.productRef ? { product_ref: opts.productRef } : {}),
+            annotations,
+        },
+        ignorees,
+    };
+}
+/* ─── Le rendu ───────────────────────────────────────────────────────────── */
+/** Un lot, rendu lisible. C'est ce que le juge reçoit et ce qu'il cite. */
+export function rendreLot(lot) {
+    const l = [];
+    l.push(`${lot.annotations.length} endroit(s) pointé(s)` +
+        (lot.outil ? ` avec ${lot.outil}` : lot.origine === "collage" ? ", collés à la main" : "") +
+        (lot.at ? ` le ${lot.at.slice(0, 10)}` : "") +
+        ".");
+    l.push("");
+    lot.annotations.forEach((a, i) => {
+        l.push(`${i + 1}. ${a.route}  ·  ${a.selector}`);
+        l.push(`   « ${a.note} »`);
+        if (a.texte)
+            l.push(`   texte de l'élément au moment du clic : « ${a.texte} »`);
+        if (a.dimensions)
+            l.push(`   ${a.dimensions.largeur} × ${a.dimensions.hauteur}`);
+        if (a.capture)
+            l.push(`   capture : ${a.capture}`);
+        if (a.brut)
+            l.push(`   gardé sans être interprété : ${Object.keys(a.brut).join(", ")}`);
+    });
+    return l.join("\n");
+}
+/** Les routes couvertes par un lot, dédoublonnées et triées. */
+export function routesDe(lot) {
+    return [...new Set(lot.annotations.map((a) => a.route))].sort();
+}

package/dist/annotations-store.js

@@ -0,0 +1,80 @@
+/**
+ * OÙ ATTERRISSENT LES ÉLÉMENTS POINTÉS.
+ *
+ * `.designwithai/annotations/<horodatage>.json`, dans le projet de la personne,
+ * plus un `latest.json` qui pointe sur le dernier lot. Rien ne part sur le
+ * réseau : ce serveur reçoit un pointage et rend un jugement.
+ *
+ * POURQUOI ON GARDE L'HISTORIQUE. Un lot décrit une SESSION de pointage — « ce
+ * jour-là, ces trois endroits gênaient ». Le dernier écrase le précédent pour
+ * la lecture courante, mais « la gêne a changé d'endroit entre les deux
+ * passages » est exactement ce qu'on veut pouvoir dire, et écraser sans garder
+ * rendrait cette phrase invérifiable.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { workspaceDir } from "./paths.js";
+import { validerLot } from "./annotation-schema.js";
+export function annotationsDir() {
+    return process.env.DWAI_ANNOTATIONS_PATH ?? workspaceDir("annotations");
+}
+/** `2026-08-20_1432` — lisible, triable, sans caractère interdit. */
+export function horodatage(now) {
+    return now.toISOString().replace(/[:.]/g, "-").replace("T", "_").replace(/Z$/, "").slice(0, 16);
+}
+export function enregistrerLot(lot, now) {
+    const dir = annotationsDir();
+    mkdirSync(dir, { recursive: true });
+    /* La date est posée ICI si elle manque : un lot sans date ne permet pas de
+       dire lequel de deux pointages est le plus récent, et c'est la seule
+       question qu'on lui posera dans six mois. */
+    const complet = { ...lot, at: lot.at || now.toISOString() };
+    const chemin = path.join(dir, `${horodatage(now)}.json`);
+    const cheminDernier = path.join(dir, "latest.json");
+    const contenu = `${JSON.stringify(complet, null, 2)}\n`;
+    writeFileSync(chemin, contenu);
+    writeFileSync(cheminDernier, contenu);
+    return { lot: complet, chemin, cheminDernier };
+}
+/**
+ * Le dernier lot, ou `null`.
+ *
+ * Il repasse par la validation à la relecture : le fichier vit dans le projet,
+ * il peut avoir été édité à la main, et une annotation sans sélecteur ferait
+ * porter une ancre incomplète à un constat.
+ */
+export function lireDernier() {
+    const f = path.join(annotationsDir(), "latest.json");
+    if (!existsSync(f))
+        return null;
+    try {
+        const v = validerLot(JSON.parse(readFileSync(f, "utf8")));
+        return v.ok ? v.lot : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** L'historique, du plus récent au plus ancien. Le pointeur `latest` exclu. */
+export function historique() {
+    const dir = annotationsDir();
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((f) => f.endsWith(".json") && f !== "latest.json")
+        .sort()
+        .reverse();
+}
+/**
+ * L'annotation qui porte cette coordonnée, dans le dernier lot.
+ *
+ * Sert à `verify_fix` : quand un constat ancré revient, on veut pouvoir citer
+ * ce que la personne avait écrit en pointant, et le texte que l'élément portait
+ * à ce moment-là — c'est le seul repli quand le sélecteur a bougé.
+ */
+export function annotationDe(a, lot = lireDernier()) {
+    if (!lot)
+        return null;
+    const canon = (s) => s.toLowerCase().replace(/\s+/g, " ").replace(/\s*([>+~,])\s*/g, "$1").trim();
+    return (lot.annotations.find((x) => canon(x.route) === canon(a.route) && canon(x.selector) === canon(a.selector)) ?? null);
+}

package/dist/autonomy-matrix.js

@@ -0,0 +1,195 @@
+/**
+ * LA MATRICE D'AUTONOMIE — une définition, un endroit.
+ *
+ * Trois régimes croisés avec la réversibilité d'un geste. Consommée par
+ * `review-agent-control` (qui juge) et `design-agent-experience` (qui produit).
+ * Personne ne la recopie : deux copies d'une matrice, et le juge finira par
+ * reprocher ce que le producteur vient d'autoriser.
+ *
+ * ELLE NE DÉCLARE PAS SES INTERDITS, ELLE LES DÉRIVE.
+ * « Un geste irréversible ne peut pas être en régime "agir seul" » n'est pas
+ * une consigne écrite quelque part qu'on pourrait oublier d'appliquer : c'est
+ * `regimeMaximal()` qui la rend impossible. Une règle déclarée se contourne en
+ * ne la lisant pas ; une règle dérivée se contourne en réécrivant la fonction,
+ * ce qui se voit.
+ *
+ * D'OÙ VIENT LA DOCTRINE. Du Vol.3 Ch.01 du Handbook, « Attribuer un niveau
+ * d'autonomie à chaque tool » : six niveaux, huit gates obligatoires, et la
+ * procédure mécanique — si un seul gate est vrai, confirmation obligatoire quel
+ * que soit le niveau nominal. Ce fichier ne réinvente pas cette doctrine, il la
+ * rend calculable. Les huit gates sont recopiés ICI et nulle part ailleurs dans
+ * le code : c'est leur seul domicile côté serveur.
+ *
+ * Aucune dépendance : ce module peut partir dans un bundle navigateur.
+ */
+/* ═══ LES TROIS RÉGIMES ════════════════════════════════════════════════════ */
+export const REGIMES = ["seul", "confirmer", "jamais"];
+export const REGIME_INFO = {
+    seul: {
+        titre: "Agir seul",
+        ce_que_ca_veut_dire: "L'agent fait, et la personne l'apprend après coup. Le geste doit pouvoir être défait sans effort par qui le découvre.",
+    },
+    confirmer: {
+        titre: "Confirmer d'abord",
+        ce_que_ca_veut_dire: "L'agent prépare et montre CE QU'IL VA FAIRE — le plan, le diff — puis attend. Un bouton « OK » sur un texte vague n'est pas une confirmation.",
+    },
+    jamais: {
+        titre: "Ne jamais faire",
+        ce_que_ca_veut_dire: "L'agent ne dispose pas de ce geste. La personne le fait elle-même, dans son outil. Retirer l'outil vaut mieux que le garder derrière une confirmation qu'on finira par cliquer machinalement.",
+    },
+};
+/* ═══ LA RÉVERSIBILITÉ ═════════════════════════════════════════════════════ */
+export const REVERSIBILITES = ["reversible", "couteux", "irreversible"];
+export const REVERSIBILITE_INFO = {
+    reversible: {
+        titre: "Réversible",
+        test: "La personne peut le défaire seule, en quelques secondes, sans demander à personne.",
+    },
+    couteux: {
+        titre: "Coûteux à annuler",
+        test: "Ça se défait, mais il faut du temps, une autre personne, ou une opération qu'on n'a pas envie de refaire. Un message envoyé qu'il faut aller rattraper.",
+    },
+    irreversible: {
+        titre: "Irréversible",
+        test: "Une fois fait, c'est fait. Une donnée supprimée, un paiement passé, un courriel parti chez un client, une promesse publique. Le technique n'est pas le seul irréversible.",
+    },
+};
+/* ═══ LES HUIT GATES — Vol.3 Ch.01, « Les gates obligatoires » ═════════════ */
+export const GATES = [
+    "publication-externe",
+    "modification-source-approuvee",
+    "suppression-ou-remplacement",
+    "changement-de-permissions",
+    "acces-donnees-sensibles",
+    "migration-ou-schema",
+    "cout-externe",
+    "decision-produit-irreversible",
+];
+export const GATE_INFO = {
+    "publication-externe": "La donnée sort du produit — envoi, export vers un tiers, publication.",
+    "modification-source-approuvee": "Le geste touche une source que quelqu'un a validée.",
+    "suppression-ou-remplacement": "Quelque chose disparaît ou est écrasé. Fusionner, c'est supprimer.",
+    "changement-de-permissions": "Qui peut faire quoi change.",
+    "acces-donnees-sensibles": "Le geste lit ou déplace des données qu'on ne montre pas à tout le monde.",
+    "migration-ou-schema": "La forme des données change.",
+    "cout-externe": "Le geste engage de l'argent, un quota, ou un abonnement.",
+    "decision-produit-irreversible": "Le geste engage le produit d'une manière qu'on ne défera pas.",
+};
+/**
+ * LE RÉGIME LE PLUS LIBRE QU'UN GESTE PUISSE PRENDRE.
+ *
+ * La règle du Handbook, rendue calculable : un seul gate vrai, et la
+ * confirmation devient obligatoire quel que soit le niveau nominal. La
+ * réversibilité s'y ajoute — un geste irréversible n'atteint jamais « agir
+ * seul », même sans gate, parce que « je le défais » n'existe pas pour lui.
+ *
+ * Ce que cette fonction NE fait pas : choisir. Elle donne le plafond ; descendre
+ * en dessous est un choix d'équipe parfaitement légitime, et la sur-confirmation
+ * se juge ailleurs (voir `ecarts`).
+ */
+export function regimeMaximal(reversibilite, gates) {
+    if (reversibilite === "irreversible")
+        return "confirmer";
+    if (gates.length > 0)
+        return "confirmer";
+    return "seul";
+}
+const RANG = { seul: 0, confirmer: 1, jamais: 2 };
+/** Un régime est-il plus libre qu'un autre ? */
+export function plusLibreQue(a, b) {
+    return RANG[a] < RANG[b];
+}
+/**
+ * Les écarts entre ce qui est DÉCLARÉ et ce que la matrice permet.
+ *
+ * DEUX SENS, ET LE SECOND SURPREND. Trop libre est le défaut qu'on attend :
+ * un geste irréversible laissé en « agir seul ». Mais la sur-confirmation en
+ * est un aussi, et il est plus répandu — demander confirmation de tout revient
+ * à ne rien protéger. Au bout de la trentième boîte de dialogue, la personne
+ * clique sans lire, et la confirmation qui comptait vraiment passe avec les
+ * autres. C'est le Vol.3 Ch.01 qui l'écrit : regrouper les actions à faible
+ * risque, exposer un plan avant les actions coûteuses.
+ *
+ * Un juge qui féliciterait la prudence excessive laisserait passer le défaut
+ * qui rend toutes les gardes inutiles.
+ */
+export function ecarts(gestes) {
+    const out = [];
+    for (const g of gestes) {
+        const plafond = regimeMaximal(g.reversibilite, g.gates);
+        if (plusLibreQue(g.regime, plafond)) {
+            const raisons = [];
+            if (g.reversibilite === "irreversible")
+                raisons.push("il est irréversible");
+            for (const gate of g.gates)
+                raisons.push(`il déclenche « ${gate} » (${GATE_INFO[gate]})`);
+            out.push({
+                kind: "trop-libre",
+                geste: g.nom,
+                regime: g.regime,
+                plafond,
+                /* Un irréversible laissé sans garde est bloquant : on engage ce qu'on
+                   ne défera pas. Un geate simplement gaté est critique : la règle
+                   existe et sera contournée, elle n'est pas absente. Même arbitrage
+                   que le modèle de sévérité de la maison. */
+                severite: g.reversibilite === "irreversible" ? "bloquant" : "critique",
+                preuve: `« ${g.nom} » est déclaré en régime « ${REGIME_INFO[g.regime].titre} » alors que ` +
+                    `${raisons.join(" et ")} — la matrice plafonne à « ${REGIME_INFO[plafond].titre} ».`,
+            });
+            continue;
+        }
+        if (g.regime === "confirmer" && plafond === "seul") {
+            out.push({
+                kind: "sur-confirmation",
+                geste: g.nom,
+                severite: "majeur",
+                preuve: `« ${g.nom} » est réversible et ne déclenche aucun gate, et pourtant il demande ` +
+                    "confirmation. Chaque confirmation inutile use celles qui comptent : au bout de la " +
+                    "trentième, on clique sans lire.",
+            });
+        }
+        if (!g.raison || g.raison.trim().length === 0) {
+            out.push({
+                kind: "sans-raison",
+                geste: g.nom,
+                severite: "mineur",
+                preuve: `« ${g.nom} » porte un régime sans raison écrite : dans six mois, personne ne saura pourquoi.`,
+            });
+        }
+    }
+    return out;
+}
+/**
+ * La matrice rendue lisible — l'artefact que le producteur pose et que le juge lit.
+ *
+ * Une ligne par geste, et la colonne qui compte est la dernière : ce que la
+ * matrice permet, à côté de ce qui est déclaré. Un tableau qui ne montrerait
+ * que le déclaré se relit sans jamais se contester.
+ */
+export function rendreMatrice(gestes) {
+    const l = [];
+    l.push("Geste | Réversibilité | Gates | Régime déclaré | Plafond de la matrice");
+    for (const g of gestes) {
+        const plafond = regimeMaximal(g.reversibilite, g.gates);
+        l.push([
+            g.nom,
+            REVERSIBILITE_INFO[g.reversibilite].titre,
+            g.gates.length ? g.gates.join(", ") : "aucun",
+            REGIME_INFO[g.regime].titre,
+            REGIME_INFO[plafond].titre + (plusLibreQue(g.regime, plafond) ? "  ← DÉPASSÉ" : ""),
+        ].join(" | "));
+    }
+    return l.join("\n");
+}
+/**
+ * Les questions qu'on pose quand un geste est ambigu.
+ *
+ * Le producteur les emploie, une à la fois, et n'y répond JAMAIS à la place de
+ * l'équipe : la réversibilité d'un geste dépend du métier, pas du code. « Est-ce
+ * qu'un envoi se rattrape chez vous ? » n'a pas de réponse générale.
+ */
+export const QUESTIONS_AMBIGU = {
+    reversibilite: "Si l'agent fait ça par erreur, qu'est-ce qu'il faut pour revenir en arrière — un clic, une heure, ou rien ne le défait ?",
+    gates: "Est-ce que ce geste fait sortir une donnée, en supprime une, change qui peut faire quoi, ou engage de l'argent ?",
+    regime: "Tu préfères que l'agent le fasse seul et te le dise après, qu'il te montre ce qu'il va faire et attende, ou qu'il ne l'ait simplement pas ?",
+};