designwithai-mcp 0.6.0 → 0.12.0

package/README.md

@@ -107,11 +107,22 @@ 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É |
+| `craft_report` | Mesure les règles de l'art : espacements, tailles, couleurs, rayons, bascules, cibles | **déterministe, zéro modèle** ; dit toujours contre quoi il a mesuré |
+| `list_craft_rules` | Le référentiel : chaque règle, sa mesure, sa tolérance, ses exceptions, sa source | une règle non calculable n'y entre pas |
+| `declare_source_of_truth` *(étendu)* | Déclare aussi le SYSTÈME : base d'espacement, ratio typo, bascules, plancher de cible | ce qui est déclaré fait foi — la convention ne passe jamais devant |
+| `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 +131,98 @@ 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.
+
+### Les règles de l'art, mesurées et non récitées
+
+Les conventions du métier — base 8, échelles à ratio, plages de bascule — entrent
+dans le produit **codifiées**, pas en dogme dans un prompt. Chaque règle est un
+objet (`craft-rules.ts`) : un identifiant stable, la fonction qui la calcule
+(`craft-measures.ts`, pur et sans modèle), sa tolérance, ses exceptions, et le
+chapitre du manuel qui la fonde — vérifié contre le manuel par un test.
+
+**Une règle qu'aucune fonction ne peut calculer n'entre pas dans le
+référentiel.** Elle reste dans le `SKILL.md` du juge concerné, où elle a
+toujours vécu.
+
+Et la préséance, qui empêche le référentiel de devenir un dogme :
+
+1. **le système DÉCLARÉ fait foi.** Une base de 5 pixels déclarée et tenue n'est
+   pas un défaut de grille ;
+2. à défaut, **la cohérence interne** mesurée sur le code ;
+3. à défaut de tout, **la convention** — annoncée comme telle dans la phrase.
+
+Un rapport dit toujours contre quoi il a mesuré. `better-layout`,
+`better-responsive`, `better-interface` et `better-consistency` appellent
+`craft_report` en premier : ils interprètent et priorisent des chiffres, ils ne
+les refont pas à l'œil.
+
 **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);
+}