designwithai-mcp 0.1.0

package/README.md

@@ -0,0 +1,153 @@
+# designwithai-mcp
+
+Le serveur MCP du Handbook Design With AI. Il expose la **source de vérité
+éditoriale** — le même `handbook.json` que sert le site — à Claude ou à un IDE,
+en **Resources** (pour lire) et en **Tools** (pour agir).
+
+Principe : les outils **imposent la méthode du Handbook**, ils ne distribuent pas
+des réponses. `review_artifact` exige une référence d'artefact ; les outils de
+plan renvoient des **gates à franchir**, pas des solutions clé en main.
+
+## Une seule source, deux surfaces
+
+Le serveur ne contient aucun contenu : il lit `handbook.json`. Une modification
+d'un chapitre, régénérée au build du site, apparaît ici comme sur le site — sans
+copie divergente. C'est garanti par construction.
+
+Ordre de résolution du fichier :
+
+1. `HANDBOOK_PATH` — chemin d'un fichier (erreur s'il manque) ;
+2. `out/handbook.json` puis `public/handbook.json` du dépôt ;
+3. `HANDBOOK_URL`, sinon `https://designwithai.fr/handbook.json`.
+
+Il faut donc soit avoir buildé le site (`STATIC_EXPORT=1 npx next build` →
+`out/handbook.json`), soit pointer `HANDBOOK_URL` sur une instance en ligne.
+
+## Installer
+
+Le serveur est publié sur npm : rien à cloner, rien à construire.
+
+```bash
+claude mcp add designwithai \
+  --env DWAI_TOKEN=dwai_TON_JETON \
+  -- npx -y designwithai-mcp
+```
+
+Le jeton se génère depuis ton compte sur https://designwithai.fr/compte — c'est
+lui qui fait remonter les audits dans ton tableau de bord. Sans lui, le serveur
+fonctionne quand même : seule la remontée est désactivée.
+
+**Où le serveur écrit.** Tes revues, décisions, profil et état vont dans
+`.designwithai/` **du dossier depuis lequel ton éditeur a été lancé** — donc dans
+ton projet, avec le produit qu'ils décrivent. `DWAI_WORKSPACE` permet d'imposer
+un autre dossier.
+
+**Recherche sémantique (facultative).** Le classement par mots-clés fonctionne
+d'origine. Pour y ajouter la recherche sémantique, installe la bibliothèque de
+modèles à côté — elle pèse plusieurs centaines de mégaoctets, d'où son caractère
+facultatif :
+
+```bash
+npm i @huggingface/transformers
+```
+
+Son absence ne provoque aucune erreur : la recherche retombe sur les mots-clés.
+
+## Développer depuis le dépôt
+
+```bash
+cd mcp
+npm install
+npm run build        # → dist/server.js
+```
+
+## Brancher sur Claude Desktop
+
+Dans `claude_desktop_config.json` :
+
+```json
+{
+  "mcpServers": {
+    "designwithai": {
+      "command": "node",
+      "args": ["/Users/boomer/designwithai/mcp/dist/server.js"],
+      "env": {
+        "HANDBOOK_PATH": "/Users/boomer/designwithai/out/handbook.json"
+      }
+    }
+  }
+}
+```
+
+## Brancher sur Claude Code
+
+```bash
+claude mcp add designwithai \
+  --env HANDBOOK_PATH=/Users/boomer/designwithai/out/handbook.json \
+  -- node /Users/boomer/designwithai/mcp/dist/server.js
+```
+
+## Ce qu'il expose
+
+**Resources** — chaque unité du Handbook à son URI `handbook://…` (chapitres,
+règles, anti-patterns, prompts, checklists, scorecards), en lecture.
+
+**Tools**
+
+| Outil | Ce qu'il fait | Garde-fou |
+|---|---|---|
+| `search_handbook` | Cherche dans le Handbook | Chaque résultat cite source + version |
+| `recommend_workflow` | Objectif → séquence de gates | Des gates, pas une solution |
+| `review_artifact` | Artefact → grille de critères à confronter | **Refuse sans référence d'artefact** |
+| `build_action_plan` | Situation → plan de gates priorisés | Ce qu'il faut produire, pas des conseils |
+| `set_profile` | Déclare le profil projet pour la session | Recos contextualisées sans le redonner |
+| `save_review` | Enregistre un issue register de skill comme artefact suivi | **Refuse sans référence d'artefact** |
+| `list_reviews` | Liste les reviews (par artefact / skill) | — |
+| `compare_reviews` | Régression entre deux passes : résolus / nouveaux / persistants | — |
+| `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** |
+| `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 |
+
+**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`.
+
+Le profil est chargé au démarrage depuis `.designwithai/profile.json` (ou `DWAI_PROFILE` / `DWAI_PROFILE_PATH`). Une fois posé, son `delivery_mode` sert de défaut à tous les outils. Les reviews sont stockées dans `.designwithai/reviews/` (surchargeable par `DWAI_REVIEWS_PATH`).
+
+Tous acceptent `delivery_mode` (`ai-builder` / `classique` / `hybride`) et
+filtrent comme le fait le site.
+
+**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
+(`artifact`, `objective`, `delivery_mode`, `source_of_truth`, `constraints`).
+Chargés depuis `../skills` par défaut, surchargeable par `SKILLS_PATH`.
+
+## Brancher le pont éditeur → compte
+
+`push_audit` fait remonter une review enregistrée vers le compte de l'utilisateur,
+pour qu'elle apparaisse dans son cockpit sur n'importe quel appareil. Deux
+variables, dans la config de l'éditeur — **jamais dans le dépôt** :
+
+```bash
+claude mcp add designwithai \
+  --env HANDBOOK_PATH=/Users/boomer/designwithai/out/handbook.json \
+  --env DWAI_TOKEN=dwai_… \
+  --env DWAI_INGEST_URL=https://hbugvurcdmimhvvfdlos.supabase.co/functions/v1/ingest-audit \
+  -- node /Users/boomer/designwithai/mcp/dist/server.js
+```
+
+Le jeton se génère dans **Compte → « Connecter mon éditeur »**, s'affiche une seule
+fois, et se révoque au même endroit. Il ne donne aucun droit de lecture : il ne
+sert qu'à écrire un audit sous le compte qui l'a créé. La clé `service_role`,
+elle, n'existe que dans l'Edge Function `ingest-audit` — ni ici, ni dans le
+bundle du site.
+
+## Développer
+
+```bash
+npm run dev          # tsx, sans build
+```

package/dist/connectors.js

@@ -0,0 +1,76 @@
+/**
+ * Connecteurs — la réalité du projet.
+ *
+ * Le MCP apporte la MÉTHODE (handbook.json). Les connecteurs apportent la
+ * RÉALITÉ : ce qui est réellement codé, documenté, livré. Les connecteurs
+ * DISTANTS (Figma, Supabase live, GitHub) passent par leurs propres serveurs MCP
+ * — inutile de les réimplémenter. Ce module fait le connecteur qu'aucun autre ne
+ * fait : la lecture d'un DÉPÔT LOCAL, pour ancrer l'analyse dans le vrai code.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import path from "node:path";
+function dirExists(p) {
+    return existsSync(p) && statSync(p).isDirectory();
+}
+export function readRepoSnapshot(repoPath) {
+    if (!existsSync(repoPath))
+        return { error: `Chemin introuvable : ${repoPath}` };
+    let name;
+    let deps = {};
+    const pkgPath = path.join(repoPath, "package.json");
+    if (existsSync(pkgPath)) {
+        try {
+            const p = JSON.parse(readFileSync(pkgPath, "utf8"));
+            name = p.name;
+            deps = { ...(p.dependencies ?? {}), ...(p.devDependencies ?? {}) };
+        }
+        catch {
+            /* package.json illisible */
+        }
+    }
+    const has = (k) => Object.keys(deps).some((d) => d.includes(k));
+    const framework = [];
+    if (has("next"))
+        framework.push("Next.js");
+    else if (has("react"))
+        framework.push("React");
+    if (has("vue"))
+        framework.push("Vue");
+    if (has("svelte"))
+        framework.push("Svelte");
+    if (has("tailwind"))
+        framework.push("Tailwind");
+    if (has("@supabase"))
+        framework.push("Supabase");
+    if (has("storybook"))
+        framework.push("Storybook");
+    const tokensPresent = ["tokens.json", "src/app/globals.css", "app/globals.css", "src/styles/globals.css", "styles/globals.css"].some((f) => existsSync(path.join(repoPath, f)));
+    let compDir = null;
+    let count = 0;
+    let sample = [];
+    for (const c of ["src/components", "components", "app/components", "src/lib/components"]) {
+        if (dirExists(path.join(repoPath, c))) {
+            const files = readdirSync(path.join(repoPath, c)).filter((f) => /\.(tsx|jsx|vue|svelte)$/.test(f));
+            compDir = c;
+            count = files.length;
+            sample = files.slice(0, 8).map((f) => f.replace(/\.\w+$/, ""));
+            break;
+        }
+    }
+    const sources = {
+        repository: "connecté",
+        storybook: dirExists(path.join(repoPath, ".storybook")) || has("storybook") ? "connecté" : "absent",
+        supabase: dirExists(path.join(repoPath, "supabase")) || has("@supabase") ? "connecté" : "absent",
+        tokens: tokensPresent ? "connecté" : "absent",
+        figma: "distant", // ne se lit pas localement — via le serveur MCP Figma
+        production: "distant", // via l'URL de prod déclarée dans le profil
+    };
+    return {
+        path: repoPath,
+        name,
+        framework,
+        dependencies: Object.keys(deps).length,
+        sources,
+        components: { dir: compDir, count, sample },
+    };
+}

package/dist/decisions.js

@@ -0,0 +1,67 @@
+/**
+ * Les décisions traçables (Architecture/Design Decision Records).
+ *
+ * Transforme une analyse en décision persistante et citable : contexte, preuves,
+ * options, décision, risques acceptés, critères de réévaluation, et les règles
+ * du Handbook utilisées (avec leur version). C'est cette traçabilité qui rend le
+ * système utile aux ÉQUIPES, pas seulement à un utilisateur isolé.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { workspaceDir } from "./paths.js";
+export function decisionsDir() {
+    return process.env.DWAI_DECISIONS_PATH ?? workspaceDir("decisions");
+}
+function slug(s) {
+    return s
+        .toLowerCase()
+        .normalize("NFD")
+        .replace(/[̀-ͯ]/g, "")
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "")
+        .slice(0, 40);
+}
+export function formatDecision(d) {
+    const list = (items) => items && items.length ? items.map((x) => `- ${x}`).join("\n") : "- —";
+    return (`# ${d.title}\n\n` +
+        `_${d.id} · ${d.created_at}_\n\n` +
+        (d.artifact_ref ? `**Artefact** : ${d.artifact_ref}\n\n` : "") +
+        `## Contexte\n${d.context || "—"}\n\n` +
+        `## Preuves\n${list(d.evidence)}\n\n` +
+        `## Options envisagées\n${list(d.options)}\n\n` +
+        `## Décision\n${d.decision}\n\n` +
+        `## Risques acceptés\n${list(d.accepted_risks)}\n\n` +
+        `## Critères de réévaluation\n${list(d.review_criteria)}\n\n` +
+        `## Règles du Handbook utilisées\n${list(d.sources)}\n`);
+}
+export function saveDecision(input, now) {
+    const stamp = now.toISOString();
+    const compact = stamp.replace(/[:.]/g, "-").replace("T", "_").replace(/Z$/, "").slice(0, 16);
+    const dir = decisionsDir();
+    mkdirSync(dir, { recursive: true });
+    let id = `${slug(input.title)}-${compact}`;
+    for (let n = 2; existsSync(path.join(dir, `${id}.md`)); n++)
+        id = `${slug(input.title)}-${compact}-${n}`;
+    const decision = { ...input, id, created_at: stamp };
+    const markdown = formatDecision(decision);
+    writeFileSync(path.join(dir, `${id}.md`), markdown);
+    writeFileSync(path.join(dir, `${id}.json`), `${JSON.stringify(decision, null, 2)}\n`);
+    return { decision, path: path.join(dir, `${id}.md`), markdown };
+}
+export function listDecisions() {
+    const dir = decisionsDir();
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const f of readdirSync(dir)) {
+        if (!f.endsWith(".json"))
+            continue;
+        try {
+            out.push(JSON.parse(readFileSync(path.join(dir, f), "utf8")));
+        }
+        catch {
+            /* ignoré */
+        }
+    }
+    return out.sort((a, b) => b.created_at.localeCompare(a.created_at));
+}

package/dist/embeddings.js

@@ -0,0 +1,98 @@
+/**
+ * Recherche sémantique — côté runtime.
+ *
+ * Charge les embeddings pré-calculés (handbook-embeddings.json) SI présents, et
+ * embed la requête avec le même modèle local. Combiné aux mots-clés, ça permet
+ * de trouver par le sens : « produire une interface » remonte les chapitres
+ * prompt-to-UI même sans mot commun.
+ *
+ * Dégradation gracieuse : pas de fichier d'embeddings → le module reste inerte
+ * (jamais de chargement du modèle), la recherche retombe sur les mots-clés.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+let corpus; // undefined = pas encore lu
+function embeddingsPath() {
+    if (process.env.HANDBOOK_EMBEDDINGS_PATH)
+        return process.env.HANDBOOK_EMBEDDINGS_PATH;
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    return path.join(here, "..", "handbook-embeddings.json");
+}
+export function loadCorpusEmbeddings() {
+    if (corpus !== undefined)
+        return corpus;
+    const p = embeddingsPath();
+    if (!existsSync(p)) {
+        corpus = null;
+        return null;
+    }
+    try {
+        corpus = JSON.parse(readFileSync(p, "utf8"));
+    }
+    catch {
+        corpus = null;
+    }
+    return corpus;
+}
+export function semanticAvailable() {
+    return loadCorpusEmbeddings() !== null;
+}
+// Le modèle n'est chargé qu'à la première requête, et seulement si des embeddings
+// existent. Import dynamique : la lib ML n'entre jamais dans le graphe sinon.
+let extractor = null;
+async function getExtractor() {
+    if (extractor)
+        return extractor;
+    const mod = (await import("@huggingface/transformers"));
+    extractor = await mod.pipeline("feature-extraction", "Xenova/paraphrase-multilingual-MiniLM-L12-v2");
+    return extractor;
+}
+/**
+ * La bibliothèque de modèles pèse plus d'un demi-gigaoctet. L'imposer à
+ * l'installation reviendrait à faire attendre un demi-giga à quelqu'un qui veut
+ * juste brancher son éditeur — elle est donc facultative, et son absence doit se
+ * traduire par une recherche par mots-clés, pas par une panne.
+ *
+ * Une seule tentative : si l'import échoue, on ne le retente pas à chaque
+ * requête. La recherche par mots-clés, elle, n'a jamais cessé de fonctionner.
+ */
+let semanticUsable = null;
+export async function trySemanticScores(query) {
+    if (semanticUsable === false)
+        return null;
+    if (!semanticAvailable())
+        return null;
+    try {
+        const scores = semanticScores(await embedQuery(query));
+        semanticUsable = true;
+        return scores;
+    }
+    catch {
+        semanticUsable = false;
+        return null;
+    }
+}
+export async function embedQuery(text) {
+    const ex = await getExtractor();
+    const out = await ex(text.slice(0, 2000), { pooling: "mean", normalize: true });
+    return Array.from(out.data);
+}
+/** Vecteurs normalisés → le cosinus est le simple produit scalaire. */
+export function cosine(a, b) {
+    let dot = 0;
+    const n = Math.min(a.length, b.length);
+    for (let i = 0; i < n; i++)
+        dot += a[i] * b[i];
+    return dot;
+}
+/** uri → similarité cosinus pour un vecteur de requête. */
+export function semanticScores(queryVec) {
+    const c = loadCorpusEmbeddings();
+    const m = new Map();
+    if (!c)
+        return m;
+    for (const uri in c)
+        m.set(uri, cosine(queryVec, c[uri]));
+    return m;
+}

package/dist/evals.js

@@ -0,0 +1,172 @@
+/**
+ * Le banc d'éval des skills.
+ *
+ * Ce que le Handbook prêche (Vol.2 Ch.06 : « gèle un dataset d'éval »), les
+ * skills doivent le tenir. Ce module charge un corpus par skill (`skills/<skill>/
+ * evals/cases.json`) et SCORE une review candidate contre sa golden review :
+ * détection, faux positifs, respect du périmètre, verdict, refus. Les résultats
+ * s'agrègent en une scorecard — le score qui rend « assurance qualité » crédible.
+ *
+ * L'exécution du skill (LLM) est faite par Claude ; ce module fournit le corpus
+ * (aveugle, sans golden) et la mesure. Tout est déterministe et testable.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { workspaceDir, skillsRoot } from "./paths.js";
+import { matches } from "./finding-identity.js";
+function skillsDir() {
+    return skillsRoot();
+}
+export function loadCases(skill) {
+    const p = path.join(skillsDir(), skill, "evals", "cases.json");
+    if (!existsSync(p))
+        return [];
+    try {
+        return JSON.parse(readFileSync(p, "utf8"));
+    }
+    catch {
+        return [];
+    }
+}
+export function getCase(caseId) {
+    const dir = skillsDir();
+    if (!existsSync(dir))
+        return null;
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const found = loadCases(entry.name).find((c) => c.id === caseId);
+        if (found)
+            return found;
+    }
+    return null;
+}
+// ─── Scoring ─────────────────────────────────────────────────────────────────
+function findingText(f) {
+    return [f.location, f.category, f.summary, f.correction].filter(Boolean).join(" ");
+}
+/**
+ * Le matcher n'habite plus ici.
+ *
+ * Mots vides, mots de contenu, recouvrement et plancher de deux mots partagés
+ * vivent désormais dans `finding-identity.ts`, avec la définition de
+ * l'équivalence entre deux constats. Trois surfaces s'en servent — ce banc,
+ * `compare_reviews` et le cockpit du site — et elles en avaient trois versions
+ * qui divergeaient. Une seule définition, sinon deux écrans donnent deux
+ * chiffres pour la même réalité.
+ */
+function phraseMatched(phrase, findings) {
+    return findings.some((f) => matches(phrase, findingText(f)));
+}
+/**
+ * Un finding inventé ne compte comme FAUX POSITIF que s'il est SIGNIFICATIF :
+ * sévérité majeure et au-delà. Un audit de bout en bout (les orchestrateurs)
+ * produit légitimement des notes de faible sévérité sur un produit sain — les
+ * compter rendrait tout cas `conformant` inatteignable. Sévérité absente ou
+ * inconnue : traitée comme significative — le doute ne protège pas le skill.
+ */
+function isSignificant(f) {
+    const s = f.severity;
+    return s !== "mineur" && s !== "note";
+}
+export function scoreCase(c, cand, now) {
+    const g = c.golden;
+    const detectedArr = g.expected_findings.filter((p) => phraseMatched(p, cand.findings));
+    const missed = g.expected_findings.filter((p) => !phraseMatched(p, cand.findings));
+    const forbidden_hits = g.forbidden_findings.filter((p) => phraseMatched(p, cand.findings));
+    const detection_rate = g.expected_findings.length
+        ? detectedArr.length / g.expected_findings.length
+        : 1;
+    const refusal_ok = (g.should_refuse ?? false) === (cand.refused ?? false);
+    // Un verdict attendu mais absent est un ÉCHEC : le verdict fait partie de ce que
+    // le banc prouve. Aucun verdict attendu → la condition ne s'applique pas.
+    const verdict_ok = !g.expected_verdict ? true : cand.verdict === g.expected_verdict;
+    const scope_ok = forbidden_hits.length === 0;
+    const extras = cand.findings.filter((f) => !g.expected_findings.some((p) => matches(p, findingText(f))));
+    const extra_findings = extras.length;
+    const extra_significant = extras.filter(isSignificant).length;
+    // Passe si : refus correct, périmètre respecté, verdict conforme quand il est
+    // attendu, détection ≥ 75 %, et (cas conformant ou hors-périmètre) aucun faux
+    // positif significatif — les notes de faible sévérité restent permises.
+    const noFalsePositiveNeeded = c.kind === "conformant" || c.kind === "out-of-scope";
+    const passed = refusal_ok &&
+        scope_ok &&
+        verdict_ok &&
+        detection_rate >= 0.75 &&
+        (!noFalsePositiveNeeded || extra_significant === 0) &&
+        (!g.should_refuse || Boolean(cand.refused));
+    return {
+        case_id: c.id,
+        skill: c.skill,
+        kind: c.kind,
+        expected: g.expected_findings.length,
+        detected: detectedArr.length,
+        missed,
+        detection_rate,
+        forbidden_hits,
+        scope_ok,
+        verdict_ok,
+        refusal_ok,
+        extra_findings,
+        extra_significant,
+        passed,
+        scored_at: now.toISOString(),
+    };
+}
+// ─── Stockage & agrégation ───────────────────────────────────────────────────
+function resultsPath(skill) {
+    const base = process.env.DWAI_EVALS_PATH ?? workspaceDir("evals");
+    return path.join(base, `${skill}.json`);
+}
+export function saveScore(score) {
+    const p = resultsPath(score.skill);
+    mkdirSync(path.dirname(p), { recursive: true });
+    let store = {};
+    if (existsSync(p)) {
+        try {
+            store = JSON.parse(readFileSync(p, "utf8"));
+        }
+        catch {
+            store = {};
+        }
+    }
+    store[score.case_id] = score;
+    writeFileSync(p, `${JSON.stringify(store, null, 2)}\n`);
+    return p;
+}
+/** Anciens résultats (scorés avant la règle de sévérité) : repli sur extra_findings. */
+function significantExtras(s) {
+    const v = s.extra_significant;
+    return v ?? s.extra_findings;
+}
+export function scorecard(skill) {
+    const total = loadCases(skill).length;
+    const p = resultsPath(skill);
+    let store = {};
+    if (existsSync(p)) {
+        try {
+            store = JSON.parse(readFileSync(p, "utf8"));
+        }
+        catch {
+            store = {};
+        }
+    }
+    const scores = Object.values(store);
+    const n = scores.length;
+    const avg = (xs) => (xs.length ? xs.reduce((a, b) => a + b, 0) / xs.length : null);
+    const withExpected = scores.filter((s) => s.expected > 0);
+    const noDefect = scores.filter((s) => s.kind === "conformant" || s.kind === "out-of-scope");
+    return {
+        skill,
+        cases_total: total,
+        cases_tested: n,
+        detection_rate: avg(withExpected.map((s) => s.detection_rate)),
+        false_positive_rate: noDefect.length === 0
+            ? null
+            : noDefect.filter((s) => significantExtras(s) > 0).length / noDefect.length,
+        scope_adherence: n === 0 ? null : scores.filter((s) => s.scope_ok).length / n,
+        refusal_accuracy: n === 0 ? null : scores.filter((s) => s.refusal_ok).length / n,
+        passed: scores.filter((s) => s.passed).length,
+        last_validated: n === 0 ? null : scores.map((s) => s.scored_at).sort().at(-1) ?? null,
+    };
+}