designwithai-mcp 0.1.0

package/dist/finding-identity.js

@@ -0,0 +1,229 @@
+/**
+ * L'IDENTITÉ D'UN CONSTAT — définition unique, trois consommateurs.
+ *
+ * Le problème que ce fichier existe pour régler : « ton produit monte » est la
+ * promesse centrale du produit, et elle reposait sur trois définitions
+ * concurrentes de « c'est le même constat ».
+ *
+ *   - le banc d'évals comparait par recouvrement de mots de contenu ;
+ *   - `compare_reviews` (MCP) par `localisation|catégorie` en chaîne exacte ;
+ *   - `progressOf` (site) par `résumé@@localisation` en chaîne exacte.
+ *
+ * Les deux dernières supposent une formulation stable. Or les constats sont
+ * écrits par un modèle, qui reformule à chaque passage. Mesuré sur deux passes
+ * réelles de designwithai.fr : « 3 résolus, 3 nouveaux, 0 persistant », alors
+ * qu'un des trois problèmes était rigoureusement le même, dit autrement. Un
+ * chiffre faux et confiant est pire qu'un chiffre absent — c'est précisément ce
+ * que ce produit reproche aux autres.
+ *
+ * La définition retenue est celle qui avait déjà été durcie au banc : le
+ * recouvrement de MOTS DE CONTENU (mots vides écartés) avec un plancher de deux
+ * mots partagés. Elle vit ici, et ici seulement.
+ *
+ * CONTRAINTE À TENIR : ce fichier ne dépend de rien. Le site l'importe dans un
+ * bundle navigateur ; la moindre importation Node (`node:fs` et compagnie, comme
+ * dans `handbook.ts`) le rendrait inutilisable de ce côté et ramènerait une
+ * deuxième définition par la fenêtre.
+ */
+/**
+ * Découpe en mots, sans accents ni casse.
+ *
+ * Volontairement distinct du `tokenize` de `handbook.ts` : celui-là pilote le
+ * classement de la recherche, qu'on ne touche pas. Deux fonctions identiques
+ * aujourd'hui, deux responsabilités différentes — les mêler ferait qu'un
+ * réglage de pertinence de recherche déplacerait silencieusement les chiffres
+ * de progression.
+ */
+export function tokenize(s) {
+    return (s
+        .toLowerCase()
+        .normalize("NFD")
+        .replace(/[̀-ͯ]/g, "")
+        .match(/[a-z0-9]+/g) ?? []);
+}
+/**
+ * Mots vides FR + EN. Sans ce filtre, « revoir le layout de la page » et
+ * « libellé perfectible dans le pied de page » se recouvrent à 0,67 par les
+ * seuls mots outils.
+ */
+export const STOPWORDS = new Set([
+    // FR
+    "le", "la", "les", "un", "une", "des", "du", "de", "et", "ou", "au", "aux", "en", "dans",
+    "sur", "pour", "par", "ce", "cet", "cette", "ces", "son", "sa", "ses", "leur", "leurs",
+    "que", "qui", "quoi", "dont", "ne", "pas", "plus", "est", "sont", "etre", "ete", "avec",
+    "sans", "comme", "mais", "donc", "alors", "ainsi", "aussi", "tres", "tout", "tous",
+    "toute", "toutes", "entre", "vers", "chez", "apres", "avant", "lors", "il", "elle", "ils",
+    "elles", "nous", "vous", "on", "se",
+    // EN
+    "the", "an", "of", "to", "in", "on", "for", "and", "or", "is", "are", "was", "were", "be",
+    "been", "being", "with", "without", "from", "that", "this", "these", "those", "it", "its",
+    "as", "at", "by", "not", "no", "any", "all", "can", "has", "have", "had", "will", "would",
+    "should",
+]);
+/** Tokens porteurs de sens : hors mots vides, et plus longs que 2 caractères. */
+export function contentTokens(s) {
+    return tokenize(s).filter((t) => t.length > 2 && !STOPWORDS.has(t));
+}
+/**
+ * Recouvrement de `phrase` dans `text`, en mots de contenu : le ratio, le nombre
+ * de mots réellement partagés, et la taille de la phrase.
+ */
+export function overlapStats(phrase, text) {
+    let p = contentTokens(phrase);
+    let t = contentTokens(text);
+    if (p.length === 0) {
+        // Phrase entièrement faite de mots outils : repli sur les tokens bruts, pour
+        // ne pas rendre impossible à matcher une phrase courte mais légitime.
+        p = tokenize(phrase);
+        t = tokenize(text);
+    }
+    if (p.length === 0)
+        return { ratio: 0, shared: 0, size: 0 };
+    const set = new Set(t);
+    const shared = p.filter((tok) => set.has(tok)).length;
+    return { ratio: shared / p.length, shared, size: p.length };
+}
+/** Au moins DEUX mots de contenu partagés, dès lors que la phrase en compte deux. */
+export const MIN_SHARED = 2;
+/**
+ * CONTENANCE — « cette phrase attendue se retrouve-t-elle dans ce constat ? »
+ *
+ * L'opération du banc d'évals : une phrase de référence contre le texte d'un
+ * constat. Asymétrique par nature, d'où le ratio rapporté à la seule phrase.
+ */
+export function matches(phrase, text, threshold = 0.5) {
+    const { ratio, shared, size } = overlapStats(phrase, text);
+    return ratio >= threshold && (size < MIN_SHARED || shared >= MIN_SHARED);
+}
+/**
+ * Le texte qui identifie un constat : OÙ, DE QUOI, et QUOI.
+ *
+ * La correction proposée est délibérément exclue : c'est le champ que le modèle
+ * reformule le plus, et deux formulations du même remède ne font pas deux
+ * problèmes différents.
+ */
+export function identityText(f) {
+    return [f.location, f.category, f.summary].filter(Boolean).join(" ");
+}
+/**
+ * ÉQUIVALENCE — « ces deux constats parlent-ils du même problème ? »
+ *
+ * Symétrique, contrairement à `matches` : aucun des deux constats n'est la
+ * référence de l'autre. D'où le coefficient de Dice, qui rapporte les mots
+ * partagés à la taille des DEUX textes — un constat verbeux ne peut donc pas
+ * avaler un constat bref au seul motif qu'il le contient.
+ */
+export function compareFindings(a, b) {
+    const ta = contentTokens(identityText(a));
+    const tb = contentTokens(identityText(b));
+    // Deux constats trop courts pour être jugés au recouvrement : on retombe sur
+    // l'égalité stricte, plutôt que de faire dire n'importe quoi à un ratio calculé
+    // sur un ou deux mots.
+    if (ta.length < MIN_SHARED || tb.length < MIN_SHARED) {
+        const same = identityText(a).trim().toLowerCase() === identityText(b).trim().toLowerCase();
+        return { dice: same ? 1 : 0, shared: same ? Math.max(ta.length, tb.length) : 0 };
+    }
+    const setA = new Set(ta);
+    const setB = new Set(tb);
+    let shared = 0;
+    for (const token of setA)
+        if (setB.has(token))
+            shared++;
+    return { dice: (2 * shared) / (setA.size + setB.size), shared };
+}
+/**
+ * Le seuil d'équivalence, calibré sur des passes réelles — pas choisi au jugé.
+ *
+ * Mesures du 17 août 2026, deux passes de designwithai.fr. Problèmes RÉELLEMENT
+ * identiques : 0,37 · 0,38 · 0,55. Problèmes distincts : 0,00 · 0,04 · 0,05 ·
+ * 0,07 · 0,11 · 0,18 · 0,25 · 0,27. La frontière est donc entre 0,27 et 0,37 —
+ * 0,34 s'y place, et chacun de ces cas est épinglé par un test.
+ *
+ * Un premier réglage à 0,50, calibré sur une seule paire, laissait passer pour
+ * « résolu puis nouveau » des défauts manifestement identiques. La leçon vaut
+ * d'être écrite : un seuil se mesure sur des cas, il ne se devine pas.
+ */
+export const SAME_THRESHOLD = 0.34;
+/**
+ * Reconnaissance par la LOCALISATION.
+ *
+ * Le cas qui a fait changer d'avis : deux passes décrivant le même bouton, à la
+ * même localisation (« Bouton « Fermer ⎋ » ») et dans la même catégorie
+ * (« champs »), ne se recouvraient qu'à 0,38 — parce que leurs résumés étaient
+ * rédigés tout autrement.
+ *
+ * Un constat s'identifie d'abord par OÙ il se trouve et DE QUEL TYPE il est ; le
+ * résumé est la partie que le modèle réécrit le plus. Quand le lieu et le type
+ * concordent franchement, c'est le même constat, quoi qu'en dise la prose.
+ */
+const LOCATION_THRESHOLD = 0.6;
+function sameLocationAndKind(a, b) {
+    const ca = (a.category ?? "").trim().toLowerCase();
+    const cb = (b.category ?? "").trim().toLowerCase();
+    if (!ca || ca !== cb)
+        return false;
+    const la = contentTokens(a.location ?? "");
+    const lb = contentTokens(b.location ?? "");
+    if (la.length === 0 || lb.length === 0)
+        return false;
+    const setA = new Set(la);
+    const setB = new Set(lb);
+    let shared = 0;
+    for (const token of setA)
+        if (setB.has(token))
+            shared++;
+    return (2 * shared) / (setA.size + setB.size) >= LOCATION_THRESHOLD && shared >= MIN_SHARED;
+}
+export function sameFinding(a, b) {
+    if (sameLocationAndKind(a, b))
+        return true;
+    const { dice, shared } = compareFindings(a, b);
+    return dice >= SAME_THRESHOLD && shared >= MIN_SHARED;
+}
+/**
+ * La comparaison de deux passes — L'ÉTAPE 5 DE LA BOUCLE.
+ *
+ * Appariement glouton au meilleur score : chaque constat de la passe récente
+ * prend le constat le plus proche encore libre dans la passe précédente. Sans
+ * cette exclusivité, un constat un peu générique s'apparierait à trois anciens
+ * et l'on compterait deux « résolus » imaginaires.
+ */
+export function diffFindings(base, head) {
+    const paired = new Set();
+    const persisting = [];
+    const added = [];
+    /* Force d'un appariement, 0 s'il n'a pas lieu d'être. Une concordance de lieu
+       et de type l'emporte sur un simple recouvrement de mots : c'est la preuve la
+       plus solide dont on dispose, elle doit donc gagner les ex aequo. */
+    const strength = (a, b) => {
+        if (!sameFinding(a, b))
+            return 0;
+        const { dice } = compareFindings(a, b);
+        return sameLocationAndKind(a, b) ? 1 + dice : dice;
+    };
+    for (const candidate of head) {
+        let bestIndex = -1;
+        let bestScore = 0;
+        for (let i = 0; i < base.length; i++) {
+            if (paired.has(i))
+                continue;
+            const score = strength(candidate, base[i]);
+            if (score > bestScore) {
+                bestScore = score;
+                bestIndex = i;
+            }
+        }
+        if (bestIndex >= 0) {
+            paired.add(bestIndex);
+            persisting.push(candidate);
+        }
+        else {
+            added.push(candidate);
+        }
+    }
+    return {
+        resolved: base.filter((_, i) => !paired.has(i)),
+        added,
+        persisting,
+    };
+}

package/dist/handbook.js

@@ -0,0 +1,98 @@
+/**
+ * Chargement et interrogation de la source de vérité.
+ *
+ * Le serveur ne connaît PAS le contenu du Handbook : il lit `handbook.json`, le
+ * même artefact que le site sert. C'est ce qui garantit « une seule source,
+ * deux surfaces » — une modif de chapitre, régénérée au build, apparaît ici
+ * comme sur le site, sans copie divergente.
+ */
+import { readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+const DEFAULT_URL = "https://designwithai.fr/handbook.json";
+/** La racine du dépôt : deux niveaux au-dessus de `mcp/dist` (ou `mcp/src`). */
+function repoRoot() {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    return path.resolve(here, "..", "..");
+}
+/**
+ * Ordre de résolution, du plus explicite au plus distant :
+ *   1. `HANDBOOK_PATH` (fichier imposé — erreur s'il manque)
+ *   2. `out/handbook.json` puis `public/handbook.json` du dépôt
+ *   3. `HANDBOOK_URL`, sinon l'URL de prod
+ */
+export async function loadHandbook() {
+    const envPath = process.env.HANDBOOK_PATH;
+    if (envPath) {
+        if (!existsSync(envPath))
+            throw new Error(`HANDBOOK_PATH introuvable : ${envPath}`);
+        return { handbook: JSON.parse(await readFile(envPath, "utf8")), origin: envPath };
+    }
+    const root = repoRoot();
+    for (const p of [path.join(root, "out", "handbook.json"), path.join(root, "public", "handbook.json")]) {
+        if (existsSync(p)) {
+            return { handbook: JSON.parse(await readFile(p, "utf8")), origin: p };
+        }
+    }
+    const url = process.env.HANDBOOK_URL ?? DEFAULT_URL;
+    const res = await fetch(url);
+    if (!res.ok) {
+        throw new Error(`Aucun handbook.json local et l'URL a échoué (${url} → ${res.status}). ` +
+            `Lance un build (\`STATIC_EXPORT=1 next build\`) ou pointe HANDBOOK_PATH sur un fichier.`);
+    }
+    return { handbook: (await res.json()), origin: url };
+}
+/** Repli d'accents + minuscules → tokens alphanumériques, pour le scoring. */
+export function tokenize(s) {
+    return (s
+        .toLowerCase()
+        .normalize("NFD")
+        .replace(/[̀-ͯ]/g, "")
+        .match(/[a-z0-9]+/g) ?? []);
+}
+/** Score simple : titre fortement pondéré, corps plafonné pour éviter le biais de longueur. */
+export function scoreUnit(unit, terms) {
+    if (terms.length === 0)
+        return 0;
+    const titleSet = new Set(tokenize(unit.title));
+    const body = tokenize(unit.text);
+    let score = 0;
+    for (const t of terms) {
+        if (titleSet.has(t))
+            score += 5;
+        let n = 0;
+        for (const w of body)
+            if (w === t)
+                n++;
+        score += Math.min(n, 5);
+    }
+    return score;
+}
+/** Un extrait autour de la première occurrence d'un terme, sinon la tête du texte. */
+export function excerpt(text, rawTerms, radius = 220) {
+    const hay = text.toLowerCase();
+    let idx = -1;
+    for (const t of rawTerms) {
+        const i = hay.indexOf(t);
+        if (i >= 0 && (idx < 0 || i < idx))
+            idx = i;
+    }
+    const oneLine = (s) => s.replace(/\s+/g, " ").trim();
+    if (idx < 0)
+        return oneLine(text.slice(0, radius)) + (text.length > radius ? "…" : "");
+    const start = Math.max(0, idx - Math.floor(radius / 2));
+    const end = Math.min(text.length, idx + Math.floor(radius / 2));
+    return (start > 0 ? "…" : "") + oneLine(text.slice(start, end)) + (end < text.length ? "…" : "");
+}
+/**
+ * Même sémantique de filtrage que le site : un chapitre sans mode est commun
+ * (toujours inclus) ; un chapitre à modes n'est inclus que si le mode déclaré
+ * y figure. Les atomes ne portent pas de mode en V1 → jamais filtrés.
+ */
+export function chapterMatchesMode(unit, mode) {
+    if (!mode || unit.kind !== "chapter")
+        return true;
+    const modes = unit.delivery_modes ?? [];
+    return modes.length === 0 || modes.includes(mode);
+}

package/dist/paths.js

@@ -0,0 +1,62 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Les deux racines — et pourquoi il en faut deux.
+ *
+ * Tant que ce serveur ne se lançait que depuis le dépôt cloné, une seule racine
+ * suffisait : `dist/../..` désignait à la fois le code livré (les skills) et
+ * l'endroit où écrire (les revues, le profil). Distribué sur npm, ce raccourci
+ * casse en deux endroits à la fois : `dist/../..` tombe dans `node_modules`, on
+ * y chercherait des skills absents et on tenterait d'y écrire les revues de
+ * quelqu'un.
+ *
+ * Les deux natures se séparent proprement :
+ *
+ *   PACKAGE — ce qui voyage AVEC le serveur et ne s'écrit jamais : la
+ *   bibliothèque de skills, les embeddings du manuel. Résolu depuis le fichier
+ *   courant, donc juste quel que soit le mode d'installation.
+ *
+ *   WORKSPACE — ce qui appartient à L'UTILISATEUR et s'écrit : ses revues, ses
+ *   décisions, son profil, son état. Le bon endroit est le projet depuis lequel
+ *   il a lancé son éditeur — `process.cwd()`. C'est aussi ce qui préserve le
+ *   comportement actuel : lancé depuis la racine du dépôt, `.designwithai/`
+ *   reste exactement où il était.
+ *
+ * Les variables d'environnement (`SKILLS_PATH`, `DWAI_REVIEWS_PATH`…) restent
+ * prioritaires partout : elles seules permettent de dévier explicitement.
+ */
+/** La racine du paquet installé — `dist/..`, donc le dossier qui contient `dist`. */
+export function packageRoot() {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    return path.resolve(here, "..");
+}
+/**
+ * Le projet de l'utilisateur.
+ *
+ * `DWAI_WORKSPACE` permet de l'imposer — utile quand l'éditeur lance le serveur
+ * depuis un dossier qui n'est pas celui du projet.
+ */
+export function workspaceRoot() {
+    return process.env.DWAI_WORKSPACE ?? process.cwd();
+}
+/** Le dossier de travail local : revues, décisions, profil, état. */
+export function workspaceDir(...segments) {
+    return path.join(workspaceRoot(), ".designwithai", ...segments);
+}
+/**
+ * La bibliothèque de skills.
+ *
+ * Elle voyage dans le paquet (`prepack` la recopie depuis la racine du dépôt).
+ * En développement, le dossier n'est pas encore recopié : on retombe alors sur
+ * celui du dépôt, deux niveaux plus haut. L'ordre compte — le paquet d'abord,
+ * sinon une copie périmée du dépôt masquerait celle qu'on vient de livrer.
+ */
+export function skillsRoot() {
+    if (process.env.SKILLS_PATH)
+        return process.env.SKILLS_PATH;
+    return path.join(packageRoot(), "skills");
+}
+/** Le repli de développement : la racine du dépôt, quand on tourne depuis les sources. */
+export function repoFallback() {
+    return path.resolve(packageRoot(), "..");
+}

package/dist/profile.js

@@ -0,0 +1,79 @@
+/**
+ * Le profil projet, côté MCP.
+ *
+ * Le serveur local ne voit pas le localStorage du site. On lui donne donc le
+ * profil par un canal explicite — un fichier `.designwithai/profile.json` ou
+ * l'env `DWAI_PROFILE` — et l'outil `set_profile` permet à Claude de le poser
+ * en cours de session. Une fois connu, il contextualise les recos sans que
+ * l'utilisateur ait à redonner son mode à chaque appel.
+ *
+ * (Le pont complet avec le compte Supabase du site est l'étape D ; ici tout
+ * reste local, sans secret ni auth.)
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { workspaceDir } from "./paths.js";
+import os from "node:os";
+export function defaultProfilePath() {
+    return process.env.DWAI_PROFILE_PATH ?? workspaceDir("profile.json");
+}
+function candidates() {
+    return [
+        ...(process.env.DWAI_PROFILE_PATH ? [process.env.DWAI_PROFILE_PATH] : []),
+        workspaceDir("profile.json"),
+        path.join(os.homedir(), ".designwithai", "profile.json"),
+    ];
+}
+export function loadProfile() {
+    if (process.env.DWAI_PROFILE) {
+        try {
+            return { profile: JSON.parse(process.env.DWAI_PROFILE), origin: "env:DWAI_PROFILE" };
+        }
+        catch {
+            /* ignore un JSON d'env invalide */
+        }
+    }
+    for (const p of candidates()) {
+        if (existsSync(p)) {
+            try {
+                return { profile: JSON.parse(readFileSync(p, "utf8")), origin: p };
+            }
+            catch {
+                /* fichier illisible : on continue */
+            }
+        }
+    }
+    return { profile: null, origin: null };
+}
+export function saveProfile(profile) {
+    const p = defaultProfilePath();
+    mkdirSync(path.dirname(p), { recursive: true });
+    writeFileSync(p, `${JSON.stringify(profile, null, 2)}\n`);
+    return p;
+}
+/** Accepte un mode canonique OU un libellé humain, et le résout. */
+export function resolveDeliveryMode(v) {
+    if (!v)
+        return undefined;
+    const s = v.toLowerCase();
+    if (/(ai[\s-]?build|lovable|bolt|replit|v0)/.test(s))
+        return "ai-builder";
+    if (/hybr/.test(s))
+        return "hybride";
+    if (/(class|tradition|équipe|equipe|dév|dev)/.test(s))
+        return "classique";
+    return undefined;
+}
+/** Une ligne de contexte lisible, pour annoter les sorties d'outils. */
+export function profileSummary(p) {
+    if (!p)
+        return "";
+    const bits = [
+        p.name,
+        p.productType,
+        p.stage,
+        resolveDeliveryMode(p.deliveryMode),
+        p.dsStage ? `DS: ${p.dsStage}` : null,
+    ].filter(Boolean);
+    return bits.join(" · ");
+}

package/dist/reviews.js

@@ -0,0 +1,99 @@
+/**
+ * Les reviews comme artefacts suivis.
+ *
+ * Quand un skill (better-layout, better-interface…) produit un issue register,
+ * ce n'est pas un texte jetable : c'est un artefact. Ce module le stocke,
+ * l'horodate et permet de comparer deux passes sur le même artefact — donc de
+ * mesurer la RÉGRESSION. C'est ce qui transforme un audit ponctuel en process
+ * qualité. Stockage local, gitignored (`.designwithai/reviews/`).
+ *
+ * Le schéma d'un problème suit `skills/_shared/issue-schema.md`.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { workspaceDir } from "./paths.js";
+import { diffFindings } from "./finding-identity.js";
+export function reviewsDir() {
+    return process.env.DWAI_REVIEWS_PATH ?? workspaceDir("reviews");
+}
+function slug(s) {
+    return s
+        .toLowerCase()
+        .normalize("NFD")
+        .replace(/[̀-ͯ]/g, "")
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "")
+        .slice(0, 48);
+}
+/** Enregistre une review, en lui attribuant un id et un horodatage. */
+export function saveReview(input, now) {
+    const stamp = now.toISOString();
+    // Millisecondes incluses (pas de slice à la seconde) : deux passes rapprochées
+    // ne doivent pas partager d'id. Dédup défensive si collision à la même ms.
+    const compact = stamp.replace(/[:.]/g, "-").replace("T", "_").replace(/Z$/, "");
+    const dir = reviewsDir();
+    mkdirSync(dir, { recursive: true });
+    let id = `${slug(input.skill)}-${compact}`;
+    for (let n = 2; existsSync(path.join(dir, `${id}.json`)); n++) {
+        id = `${slug(input.skill)}-${compact}-${n}`;
+    }
+    const review = { ...input, id, created_at: stamp };
+    writeFileSync(path.join(dir, `${review.id}.json`), `${JSON.stringify(review, null, 2)}\n`);
+    return review;
+}
+export function listReviews(filter) {
+    const dir = reviewsDir();
+    if (!existsSync(dir))
+        return [];
+    const all = [];
+    for (const f of readdirSync(dir)) {
+        if (!f.endsWith(".json"))
+            continue;
+        try {
+            const r = JSON.parse(readFileSync(path.join(dir, f), "utf8"));
+            if (filter?.artifact_ref && r.artifact_ref !== filter.artifact_ref)
+                continue;
+            if (filter?.skill && r.skill !== filter.skill)
+                continue;
+            all.push(r);
+        }
+        catch {
+            /* fichier corrompu : ignoré */
+        }
+    }
+    return all.sort((a, b) => b.created_at.localeCompare(a.created_at));
+}
+export function getReview(id) {
+    const p = path.join(reviewsDir(), `${id}.json`);
+    if (!existsSync(p))
+        return null;
+    try {
+        return JSON.parse(readFileSync(p, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+/** Met à jour le statut d'un finding dans une review stockée (étape verify_fix). */
+export function updateFindingStatus(reviewId, index, status, verifiedBy) {
+    const r = getReview(reviewId);
+    if (!r || !r.findings[index])
+        return null;
+    r.findings[index] = { ...r.findings[index], status, verified_by: verifiedBy };
+    writeFileSync(path.join(reviewsDir(), `${r.id}.json`), `${JSON.stringify(r, null, 2)}\n`);
+    return r.findings[index];
+}
+/**
+ * Compare deux reviews (base = ancienne, head = récente).
+ *
+ * L'identité d'un constat vient de `finding-identity.ts`, partagée avec le banc
+ * d'évals et le cockpit du site. La version précédente comparait
+ * `localisation|catégorie` en chaîne exacte : elle tenait tant que les constats
+ * étaient écrits à la main, elle ne tient plus dès qu'un modèle les reformule
+ * d'une passe à l'autre — deux phrases pour le même défaut comptaient alors pour
+ * un résolu ET un nouveau.
+ */
+export function compareReviews(base, head) {
+    const { resolved, added, persisting } = diffFindings(base.findings, head.findings);
+    return { base, head, resolved, added, persisting };
+}