@sylad/cadence 1.8.0 → 1.10.0

package/dist/ready-free.js

@@ -0,0 +1,109 @@
+import { dirname, resolve } from 'node:path';
+import { nextUp } from './audit.js';
+import { planLoader } from './config.js';
+import { gitRoot } from './git.js';
+import { findProjects, readDepth } from './lead.js';
+import { decisionPending } from './orchestrate/continue.js';
+import { liveWaves } from './orchestrate/registry.js';
+import { readResources } from './resources.js';
+import { lotFinished, RunStore } from './orchestrate/state.js';
+/** Le dépôt d'un projet : sa racine git, ou son chemin absolu hors de git. */
+const repoOf = (dir) => gitRoot(dir) ?? resolve(dir);
+/**
+ * Un lot se reconnaît à son dépôt et à son id, pas au nom du projet : une vague lancée depuis un autre dossier l'enregistre sous `basename(dir)`
+ * (le tour d'un dossier parent le nomme par son chemin, `grp/alpha`), et deux projets de même nom de deux dossiers sont deux dépôts.
+ */
+const lotAt = (repo, lot) => `${repo}:${lot}`;
+/**
+ * Les projets qui partagent les ressources de `dir` : ceux que trouve `findProjects` sous le dossier du cadence.yaml qui déclare ses `resources:`
+ * (le plus proche en remontant, voir `readResources`), sur la profondeur `depth:` de ce fichier (un niveau à défaut) : `P/x` et `P/grp/alpha`
+ * partagent le banc que déclare `P/cadence.yaml` (`depth: 2`), d'où qu'on les interroge. Sans ressource déclarée, ou avec un cadence.yaml
+ * illisible ou une `depth:` invalide (que leur ligne de tour signale), ce sont les projets du dossier parent, sur un niveau.
+ */
+function sharingProjects(dir) {
+    try {
+        const { file, names } = readResources(repoOf(dir));
+        if (names.length)
+            return findProjects(dirname(file), readDepth(dirname(file)));
+    }
+    catch {
+        // cadence.yaml illisible ou depth: invalide
+    }
+    return findProjects(dirname(dir));
+}
+const plansOf = (dir) => planLoader(repoOf(dir))().lots();
+/**
+ * Les ressources prises à cet instant : celles des lots `doing` des projets `dirs` et de ceux qui partagent leurs ressources (`sharingProjects` : lancé depuis l'un d'eux,
+ * on voit aussi les autres), celles des lots non finis des vagues vivantes (un lot de vague n'est `doing` dans le plan qu'une fois sa session partie)
+ * et celles des lots `held` (le tirage d'une vague qui part). Avec leurs lots (`dépôt:lot`, voir `lotAt`), qui ne sont pas à proposer.
+ */
+function taken(dirs, home, held) {
+    const resources = new Set();
+    const running = new Set();
+    for (const dir of new Set([...dirs, ...dirs.flatMap(sharingProjects)])) {
+        try {
+            for (const l of nextUp(plansOf(dir)).doing)
+                for (const r of l.uses ?? [])
+                    resources.add(r);
+        }
+        catch {
+            // plan illisible : sa ligne de tour le dit, il ne tient aucune ressource connue
+        }
+    }
+    for (const w of liveWaves(home)) {
+        let live;
+        try {
+            live = RunStore.find(w.cwd, w.wave)?.lots().filter((l) => !lotFinished(l)) ?? [];
+        }
+        catch {
+            continue; // état de vague illisible : la vague ne tient aucune ressource connue
+        }
+        held = [...held, ...live];
+    }
+    for (const s of held) {
+        running.add(lotAt(repoOf(s.repo), s.lot));
+        try {
+            for (const r of plansOf(s.repo).find((l) => l.id === s.lot)?.uses ?? [])
+                resources.add(r);
+        }
+        catch {
+            // plan illisible : aucune ressource connue
+        }
+    }
+    return { resources, running };
+}
+/**
+ * Pour chaque dossier de projet de `dirs`, ses lots prêts (comme `nextUp`, hors « à décider » et hors lots d'une vague vivante) dont aucune ressource
+ * n'est prise par un lot `doing` d'un des projets (ou de ceux qui partagent leurs ressources, voir `sharingProjects`) ni par une vague vivante de `home` ni par les lots `held` d'une vague qui part. Un lot sans `uses:` n'en tient aucune : il est libre.
+ * Les projets sans lot libre n'ont pas d'entrée (clé : le dossier) ; un plan illisible est sauté.
+ */
+export function readyFree(dirs, home, held = []) {
+    const { resources, running } = taken(dirs, home, held);
+    const out = new Map();
+    for (const dir of dirs) {
+        let ready;
+        try {
+            ready = nextUp(plansOf(dir)).ready;
+        }
+        catch {
+            continue;
+        }
+        const repo = repoOf(dir);
+        const free = ready
+            .filter((l) => !decisionPending(l) && !running.has(lotAt(repo, l.id)) && !(l.uses ?? []).some((r) => resources.has(r)))
+            .map((l) => ({ id: l.id, title: l.title, ...(l.uses?.length ? { uses: l.uses } : {}) }));
+        if (free.length)
+            out.set(dir, free);
+    }
+    return out;
+}
+/** Lots listés par projet dans la ligne ; au-delà, « projet +K » (le --json donne tout). */
+const FREE_SHOWN = 3;
+/** « prêts, ressources libres : projet:L3 titre (banc) · … », au plus FREE_SHOWN lots par projet puis « projet +K », ou null quand aucun lot prêt n'est libre. */
+export function freeLine(entries, titleMax) {
+    const items = entries.flatMap((e) => [
+        ...e.free.slice(0, FREE_SHOWN).map((l) => `${e.project}:${l.id} ${l.title.length <= titleMax ? l.title : `${l.title.slice(0, titleMax - 1)}…`}${l.uses?.length ? ` (${l.uses.join(', ')})` : ''}`),
+        ...(e.free.length > FREE_SHOWN ? [`${e.project} +${e.free.length - FREE_SHOWN}`] : []),
+    ]);
+    return items.length ? `prêts, ressources libres : ${items.join(' · ')}` : null;
+}

package/dist/ref/add.js

@@ -0,0 +1,129 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, rmSync, statSync } from 'node:fs';
+import { basename, extname, join, resolve } from 'node:path';
+import { RafError } from '../plan.js';
+import { attachRegions, citedPages, indexText } from './figures.js';
+import { DPI, extractImages, imageFile, imageRegions, listImages, pageCount, renderPages, renderThumbnails, textLayout } from './pdf.js';
+import { readDocument, writeDocument } from './store.js';
+import { requireTools } from './tools.js';
+/** Sans `--sections`, un document de cette taille ou plus petit est rendu en entier ; au-delà, seul l'index est construit. */
+export const WHOLE_DOCUMENT_MAX = 30;
+/** Une page de moins de 20 caractères de texte est tenue pour scannée (recette du skill norme-etude). */
+const SCANNED_MAX_CHARS = 20;
+/** [1, 2, 3, 6] → « 1-3, 6 ». */
+function ranges(pages) {
+    const out = [];
+    for (let i = 0; i < pages.length;) {
+        let j = i;
+        while (j + 1 < pages.length && pages[j + 1] === pages[j] + 1)
+            j++;
+        out.push(j > i ? `${pages[i]}-${pages[j]}` : String(pages[i]));
+        i = j + 1;
+    }
+    return out.join(', ');
+}
+/** `3-5,9` → [3, 4, 5, 9] (pages du PDF, 1 = première), sans doublon, dans l'ordre. */
+export function parseSections(text, pages) {
+    const out = new Set();
+    for (const part of text.split(',')) {
+        const m = /^\s*(\d+)(?:\s*-\s*(\d+))?\s*$/.exec(part);
+        if (!m)
+            throw new RafError(`ref : --sections invalide : « ${part.trim()} » (attendu : 3, 3-5 ou 3-5,9)`);
+        const from = Number(m[1]);
+        const to = m[2] === undefined ? from : Number(m[2]);
+        if (from < 1 || to < from)
+            throw new RafError(`ref : --sections invalide : « ${part.trim()} » (pages de 1 à ${pages}, début avant fin)`);
+        if (to > pages)
+            throw new RafError(`ref : --sections : page ${to} demandée, le document a ${pages} pages`);
+        for (let n = from; n <= to; n++)
+            out.add(n);
+    }
+    return [...out].sort((a, b) => a - b);
+}
+const slugOf = (file) => basename(file, extname(file)).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+export const SLUG = /^[a-z0-9][a-z0-9-]*$/;
+/**
+ * `cadence ref add` : enregistre un PDF, rend les pages visées, garde le texte positionné et les images, construit l'index des figures. Rend le dossier du document
+ * et `lues`, les pages qu'une lecture doit lire : avec `--sections`, ces pages et celles des figures qu'elles citent (pas les pages rendues par un appel précédent) ; sans, toutes les pages rendues.
+ */
+export function add(o) {
+    // Les outils d'abord : sans eux, rien n'est lu ni écrit.
+    const tools = requireTools(o.env);
+    const file = resolve(o.cwd, o.document);
+    if (!existsSync(file) || !statSync(file).isFile())
+        throw new RafError(`ref : document introuvable : ${file}`);
+    const slug = o.slug ?? slugOf(file);
+    if (!SLUG.test(slug))
+        throw new RafError(`ref : slug invalide : « ${slug} » (lettres minuscules, chiffres et tirets ; --slug pour le choisir)`);
+    const total = pageCount(tools, file);
+    const wanted = o.sections === undefined ? (total <= WHOLE_DOCUMENT_MAX ? Array.from({ length: total }, (_, i) => i + 1) : []) : parseSections(o.sections, total);
+    const sha256 = createHash('sha256').update(readFileSync(file)).digest('hex');
+    const docDir = join(o.refsDir(), slug);
+    const before = readDocument(docDir);
+    if (before && before.sha256 !== sha256) {
+        throw new RafError(`ref : le slug « ${slug} » est déjà pris par un autre document (${before.source}, empreinte ${before.sha256.slice(0, 12)}) : choisir un autre nom avec --slug`);
+    }
+    const text = textLayout(tools, file);
+    const listed = listImages(tools, file);
+    const index = indexText(text, new Set(listed.map((i) => i.page)));
+    // pages à rendre : celles visées, celles déjà rendues par un appel précédent du même document, et celles des figures qu'elles citent
+    const keep = new Set(before?.pages.filter((p) => p.rendered).map((p) => p.n));
+    const visees = new Set([...wanted, ...keep]);
+    const rendered = new Set([...visees, ...citedPages(index, visees)]);
+    const ordered = [...rendered].sort((a, b) => a - b);
+    // lecture d'abord (pdftohtml n'écrit pas dans le dossier), écriture ensuite : un échec d'outil ne laisse pas un dossier à moitié rempli
+    const regions = new Map();
+    for (const n of ordered)
+        if (listed.some((i) => i.page === n))
+            regions.set(n, imageRegions(tools, file, n));
+    const created = !existsSync(docDir);
+    try {
+        renderPages(tools, file, ordered, join(docDir, 'pages'));
+        renderThumbnails(tools, file, total, join(docDir, 'thumbs'));
+        for (const n of regions.keys())
+            extractImages(tools, file, n, join(docDir, 'images'));
+    }
+    catch (e) {
+        if (created)
+            rmSync(docDir, { recursive: true, force: true });
+        throw e;
+    }
+    const images = [];
+    const placed = [];
+    for (const img of listed) {
+        const box = regions.get(img.page)?.[img.rank - 1];
+        const stored = box && rendered.has(img.page) ? { page: img.page, file: `images/${imageFile(img.page, img.slot)}`, x: box.x, y: box.y, l: box.l, h: box.h } : { page: img.page, file: null, x: null, y: null, l: null, h: null };
+        images.push(stored);
+        placed.push({ page: img.page, box: stored.x === null ? null : { x: stored.x, y: stored.y, l: stored.l, h: stored.h } });
+    }
+    attachRegions(index, placed);
+    const pages = text.map((p) => ({ ...p, rendered: rendered.has(p.n) }));
+    const doc = {
+        slug,
+        source: file,
+        sha256,
+        added: before?.added ?? o.now.toISOString(),
+        dpi: DPI,
+        sections: o.sections ?? before?.sections ?? null,
+        tools,
+        pages,
+        images,
+        figures: index.figures,
+        unresolved: index.unresolved,
+    };
+    writeDocument(docDir, doc);
+    o.out(`${slug} : ${basename(file)}`);
+    o.out(`pages : ${total}`);
+    const sansTexte = text.filter((p) => p.lines.reduce((n, l) => n + l.text.trim().length, 0) < SCANNED_MAX_CHARS).map((p) => p.n);
+    if (sansTexte.length > 0)
+        o.out(`pages sans texte : ${sansTexte.length} (${ranges(sansTexte)}) — scannées ou faites d'images : l'index n'en dit rien, parcourir ${join(docDir, 'thumbs')} pour choisir les pages à rendre (--sections)`);
+    o.out(`rendues : ${ordered.length}${ordered.length > 0 ? ` (${ordered.join(', ')})` : ''}`);
+    o.out(`images : ${images.length}`);
+    o.out(`figures : ${index.figures.length}`);
+    o.out(`liens non résolus : ${index.unresolved.length}`);
+    o.out(`dossier : ${docDir}`);
+    if (ordered.length === 0)
+        o.out(`aucune page rendue (grand document : seul l'index est construit) — cadence ref add ${o.document} --slug ${slug} --sections 3-5 pour rendre des pages`);
+    const lues = o.sections === undefined ? ordered : [...new Set([...wanted, ...citedPages(index, new Set(wanted))])].sort((a, b) => a - b);
+    return { slug, docDir, doc, lues };
+}

package/dist/ref/analyse.js

@@ -0,0 +1,220 @@
+import { existsSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { PACKAGE_ROOT } from '../orchestrate/snapshot.js';
+import { RafError } from '../plan.js';
+import { add } from './add.js';
+import { checkInventaire, readInventaire } from './check.js';
+import { assembler, parseSeuil, reconcilier } from './diff.js';
+import { troisiemeRegard } from './regard.js';
+import { sessionDeRef } from './session.js';
+/** Plafond déclaré d'une lecture : au plus 20 pages rendues lues d'un coup (design §5, « Taille »). Au-delà, `--sections` en choisit moins. */
+export const LECTURE_PAGES_MAX = 20;
+export const ANALYSE_MODELS = ['sonnet', 'opus', 'haiku'];
+/** Sortie structurée de la session : ce que l'agent dit de sa lecture ; le programme ne s'y fie pas, il relit le fichier. */
+export const ANALYSE_SCHEMA = {
+    type: 'object',
+    properties: {
+        resume: { type: 'string', description: 'Two sentences: what the document is and what the reading holds.' },
+        questions: { type: 'array', items: { type: 'string' }, description: 'What a human must settle: a contradiction, an element that could not be read.' },
+    },
+    required: ['resume', 'questions'],
+    additionalProperties: false,
+};
+/** Consigne de la lecture : tout ce que l'agent a besoin de savoir, rien de l'attendu d'un corpus, rien d'une autre lecture. */
+function brief(o) {
+    const cadence = `node ${join(PACKAGE_ROOT, 'bin', 'cadence.js')}`;
+    const config = `--config ${o.configPath}`;
+    return [
+        `Lis le document de référence « ${o.slug} » et écris sa lecture.`,
+        '',
+        `Dossier du document : ${o.docDir} (document.json : texte positionné, images, index des figures et passages qui les citent).`,
+        `Pages rendues à 200 dpi (${o.pages.length}) :`,
+        ...o.pages.map((n) => `- ${join(o.docDir, 'pages', `page-${n}.png`)}`),
+        '',
+        `Modèle du format : ${join(PACKAGE_ROOT, 'templates', 'inventaire.json')} (genre « lecture », sans la clé pages ; slug et sha256 recopiés de document.json).`,
+        `Lecture à écrire : ${o.file}`,
+        '',
+        'Commandes :',
+        `- mesurer une zone (pixels de la page rendue) : ${cadence} ref measure ${o.slug} <page> <page | x,y | x,y,l,h> --quoi couleurs|contraste|boites|texte ${config}`,
+        `- valider la lecture, jusqu'à ce qu'elle passe : ${cadence} ref check ${o.file}`,
+        '',
+        `Ne lis que ce dossier, le modèle et les pages ci-dessus, et aucun autre fichier de ${join(o.docDir, 'lectures')} que le tien : une autre lecture du même document peut s'y trouver, la tienne doit être la seule que tu connais ; n'écris que ${o.file}. Les jetons ne sont pas à écrire : le programme les compte.`,
+    ].join('\n');
+}
+/** « 1 page lue », « 3 pages lues ». */
+const pagesLues = (n) => `${n} page${n > 1 ? 's' : ''} lue${n > 1 ? 's' : ''}`;
+/** Les écarts d'une lecture au-delà du schéma : le genre, et le document lu (jamais une mesure sur deux versions mêlées). */
+function ecartsDeLecture(lecture, doc) {
+    const l = lecture;
+    const out = [];
+    if (l.genre !== 'lecture')
+        out.push('genre : « lecture » attendu (une lecture, pas un inventaire)');
+    if (l.document?.slug !== doc.slug)
+        out.push(`document.slug : « ${String(l.document?.slug)} » n'est pas le document lu (${doc.slug})`);
+    if (l.document?.sha256 !== doc.sha256)
+        out.push(`document.sha256 : l'empreinte n'est pas celle du document lu (${doc.sha256.slice(0, 12)}…)`);
+    return out;
+}
+/** Une lecture : une session neuve de `reference-analyst` qui écrit `lectures/<nom>.json`, relue par le programme (ref check, genre, document) ; les jetons de la session y sont posés dans `usage`. */
+async function lireUne(c, nom, model) {
+    const file = join(c.docDir, 'lectures', `${nom}.json`);
+    rmSync(file, { force: true }); // une lecture d'un passage précédent ne passe jamais pour celle de celui-ci
+    const r = await sessionDeRef({
+        agent: 'reference-analyst',
+        brief: brief({ slug: c.slug, docDir: c.docDir, pages: c.pages, file, configPath: c.o.configPath }),
+        model,
+        schema: ANALYSE_SCHEMA,
+        slug: c.slug,
+        docDir: c.docDir,
+        configPath: c.o.configPath,
+        claudeHome: c.o.claudeHome,
+        claude: c.o.claude,
+        agents: c.o.agents,
+        onRelaunch: () => rmSync(file, { force: true }), // la lecture à moitié écrite de la session coupée ne passe pas pour celle de la neuve
+        echec: 'la session de lecture a échoué',
+    });
+    if (r.kind === 'quota')
+        return r;
+    if (!existsSync(file))
+        return { kind: 'refus', problems: [`aucune lecture écrite : ${file}`] };
+    let lecture;
+    try {
+        lecture = readInventaire(file);
+    }
+    catch (e) {
+        return { kind: 'refus', problems: [e.message] };
+    }
+    const schema = checkInventaire(lecture);
+    const problems = schema.length > 0 ? schema : ecartsDeLecture(lecture, c.doc);
+    if (problems.length > 0)
+        return { kind: 'refus', problems };
+    const usage = { tokens: r.tokens, modele: model, session: r.session };
+    lecture.usage = usage;
+    writeFileSync(file, `${JSON.stringify(lecture, null, 2)}\n`);
+    const structured = r.structured;
+    return { kind: 'ok', lecture, file, usage, questions: Array.isArray(structured?.questions) ? structured.questions.map(String) : [] };
+}
+const confiancesDe = (lecture) => ['mesure', 'lu', 'incertain'].map((c) => [c, lecture.elements.filter((e) => e.confiance === c).length]).filter(([, n]) => n > 0).map(([c, n]) => `${c} : ${n}`).join(', ');
+/**
+ * `cadence ref analyse` : la chaîne — add, puis UNE lecture (une session de l'agent `reference-analyst`, `lectures/a.json`) ; avec `--double`, deux lectures
+ * indépendantes (A et B, modèles possiblement différents), `ref diff` (réconciliation par le programme), le troisième regard sur ce qu'une seule lecture
+ * porte, l'inventaire écrit avec les jetons posés dans `usage` (la double lecture n'a pas montré de gain : c'est une option, pas le défaut). Rend le code de sortie : 0 fait, 1 lecture refusée ou trop d'éléments non
+ * appariés ou aucun élément gardé par le troisième regard, 3 quota ; une session en échec ou un refus d'entrée (modèle, plafond, aucune page) lève une `RafError` (code 2).
+ */
+export async function analyse(o) {
+    const model = (o.model ?? 'sonnet');
+    const modelB = (o.modelB ?? 'opus');
+    if (!ANALYSE_MODELS.includes(model))
+        throw new RafError(`ref analyse : --model invalide : « ${o.model} » (attendu : ${ANALYSE_MODELS.join(', ')})`);
+    if (!ANALYSE_MODELS.includes(modelB))
+        throw new RafError(`ref analyse : --model-b invalide : « ${o.modelB} » (attendu : ${ANALYSE_MODELS.join(', ')})`);
+    if (!o.double && o.modelB !== undefined)
+        throw new RafError('ref analyse : --model-b n\'a de sens qu\'avec --double (une seule lecture, pas de lecture B)');
+    if (!o.double && o.seuil !== undefined)
+        throw new RafError('ref analyse : --seuil n\'a de sens qu\'avec --double (une seule lecture, rien à réconcilier)');
+    const seuil = parseSeuil(o.seuil, 'ref analyse');
+    const { slug, docDir, doc, lues: pages } = add({ document: o.document, slug: o.slug, sections: o.sections, env: o.env, cwd: o.cwd, refsDir: o.refsDir, now: o.now, out: o.out });
+    const sections = `\n  choisir les pages à lire : cadence ref analyse ${o.document} --slug ${slug} --sections 3-12`;
+    if (pages.length === 0)
+        throw new RafError(`ref analyse : aucune page rendue : rien à lire${sections}`);
+    if (pages.length > LECTURE_PAGES_MAX)
+        throw new RafError(`ref analyse : ${pages.length} pages ${o.sections === undefined ? 'rendues' : 'à lire (--sections et les figures qu\'elles citent)'}, plafond d'une lecture : ${LECTURE_PAGES_MAX} pages${sections}`);
+    const c = { o, slug, docDir, doc, pages };
+    const refuse = (problems, prefixe = '') => {
+        for (const p of problems)
+            o.out(`✗ ${prefixe}${p}`);
+        o.out(`${problems.length} écart(s)`);
+        return 1;
+    };
+    if (!o.double) {
+        // les fichiers d'une double lecture précédente ne passent pas pour ceux de ce passage : leur `usage.lectures.a` ne serait plus celui de `a.json`
+        rmSync(join(docDir, 'lectures', 'b.json'), { force: true });
+        rmSync(join(docDir, 'inventaire.json'), { force: true });
+        const r = await lireUne(c, 'a', model);
+        if (r.kind === 'quota') {
+            o.err(`ref analyse : quota atteint, aucune lecture écrite : ${r.message}`);
+            return 3;
+        }
+        if (r.kind === 'refus')
+            return refuse(r.problems);
+        o.out(`${slug} : lecture unique (${model}) — ${pagesLues(pages.length)} (plafond d'une lecture : ${LECTURE_PAGES_MAX})`);
+        o.out(`lecture : ${r.file}`);
+        o.out(`éléments : ${r.lecture.elements.length} (${confiancesDe(r.lecture)})`);
+        o.out(`tokens : ${r.usage.tokens} (${Math.round(r.usage.tokens / pages.length)} par page, ${pagesLues(pages.length)})`);
+        for (const q of r.questions)
+            o.out(`question : ${q}`);
+        return 0;
+    }
+    const inventaire = join(docDir, 'inventaire.json');
+    rmSync(inventaire, { force: true }); // l'inventaire d'un passage précédent ne passe jamais pour celui de celui-ci
+    // deux sessions qui ne se voient pas : lancées ensemble, chacune écrit sa lecture ; un échec n'interrompt pas l'autre
+    const [ra, rb] = await Promise.allSettled([lireUne(c, 'a', model), lireUne(c, 'b', modelB)]);
+    for (const r of [ra, rb])
+        if (r.status === 'rejected')
+            throw r.reason;
+    const [a, b] = [ra, rb].map((r) => r.value);
+    const lues = [['A', a], ['B', b]];
+    for (const [nom, r] of lues) {
+        if (r.kind === 'quota') {
+            o.err(`ref analyse : quota atteint (lecture ${nom}), aucune réconciliation : ${r.message}`);
+            return 3;
+        }
+    }
+    const refus = lues.flatMap(([nom, r]) => (r.kind === 'refus' ? r.problems.map((p) => `lecture ${nom} : ${p}`) : []));
+    if (refus.length > 0)
+        return refuse(refus);
+    const [la, lb] = [a, b];
+    const rec = reconcilier(la.lecture, lb.lecture, seuil);
+    const pct = (x) => `${Number((x * 100).toFixed(1))} %`;
+    const compteRec = `concordants ${rec.concordants} · divergents ${rec.divergents} · seuls ${rec.seuls} · silences ${rec.silences}`;
+    if (rec.refuse) {
+        o.out(`${slug} : double lecture (A ${model}, B ${modelB}) — ${pagesLues(pages.length)} (plafond d'une lecture : ${LECTURE_PAGES_MAX})`);
+        o.out(`réconciliation : ${compteRec} — non appariés ${pct(rec.ratio)} (seuil ${pct(seuil)})`);
+        o.out(`plus de ${pct(seuil)} d'éléments non appariés (${rec.nonApparies} sur ${rec.concordants + rec.divergents + rec.seuls}) : les deux lectures ne décrivent pas le même document — question au lead, aucune réconciliation (les lectures restent dans ${join(docDir, 'lectures')}, \`cadence ref diff\` les compare)`);
+        return 1;
+    }
+    const seuls = rec.items.filter((i) => i.statut === 'seul');
+    let regard;
+    if (seuls.length > 0) {
+        const r = await troisiemeRegard({ seuls, model, slug, docDir, configPath: o.configPath, claudeHome: o.claudeHome, claude: o.claude, agents: o.agents });
+        if (r.kind === 'quota') {
+            o.err(`ref analyse : quota atteint pendant le troisième regard, aucun inventaire écrit (les lectures A et B sont gardées) : ${r.message}`);
+            return 3;
+        }
+        seuls.forEach((item, i) => (item.decision = r.decisions[i]));
+        regard = r;
+    }
+    const inv = assembler(la.lecture, lb.lecture, rec, regard !== undefined);
+    if (inv.elements.length === 0) {
+        // tout ce que les lectures portent n'était porté que par une seule d'entre elles et le troisième regard l'a écarté : rien à écrire, ce n'est pas un défaut de cadence
+        o.out(`${slug} : double lecture (A ${model}, B ${modelB}) — ${pagesLues(pages.length)} (plafond d'une lecture : ${LECTURE_PAGES_MAX})`);
+        o.out(`réconciliation : ${compteRec}`);
+        o.out(`le troisième regard a écarté tous les éléments : aucun inventaire — question au lead (les lectures restent dans ${join(docDir, 'lectures')}, \`cadence ref diff\` les compare)`);
+        return 1;
+    }
+    // la réconciliation ne produit que des éléments déjà valides : un écart ici est un défaut de cadence, jamais une lecture à refuser
+    const problems = checkInventaire(inv);
+    if (problems.length > 0)
+        throw new RafError(`ref analyse : l'inventaire réconcilié est invalide (défaut de cadence) : ${problems[0]}`);
+    const tokens = la.usage.tokens + lb.usage.tokens + (regard?.tokens ?? 0);
+    inv.usage = {
+        tokens,
+        lectures: { a: { tokens: la.usage.tokens, modele: model }, b: { tokens: lb.usage.tokens, modele: modelB }, ...(regard ? { regard: { tokens: regard.tokens, modele: model } } : {}) },
+    };
+    const verdicts = seuls.flatMap((item) => (item.decision ? [{ lecture: item.lecture, id: item.element.id, verdict: item.decision.verdict, raison: item.decision.raison }] : []));
+    inv.reconciliation = { concordants: rec.concordants, divergents: rec.divergents, seuls: rec.seuls, silences: rec.silences, non_apparies: rec.ratio, regard: verdicts };
+    writeFileSync(inventaire, `${JSON.stringify(inv, null, 2)}\n`);
+    const confirmes = verdicts.filter((v) => v.verdict === 'confirme').length;
+    const ecartes = verdicts.length - confirmes;
+    o.out(`${slug} : double lecture (A ${model}, B ${modelB}) — ${pagesLues(pages.length)} (plafond d'une lecture : ${LECTURE_PAGES_MAX})`);
+    o.out(`lectures : ${la.file}, ${lb.file}`);
+    o.out(`réconciliation : ${compteRec} — non appariés ${rec.ratio === null ? 'n/a' : pct(rec.ratio)} (seuil ${pct(seuil)})`);
+    if (regard)
+        o.out(`troisième regard (${model}) : ${confirmes} confirmé${confirmes > 1 ? 's' : ''}, ${ecartes} écarté${ecartes > 1 ? 's' : ''}, ${seuls.length - verdicts.length} sans réponse`);
+    o.out(`inventaire : ${inventaire}`);
+    o.out(`éléments : ${inv.elements.length} (${confiancesDe(inv)})`);
+    o.out(`tokens : ${tokens} (${Math.round(tokens / pages.length)} par page, ${pagesLues(pages.length)}) — A : ${la.usage.tokens}, B : ${lb.usage.tokens}${regard ? `, troisième regard : ${regard.tokens}` : ''}`);
+    for (const q of new Set([...la.questions, ...lb.questions, ...(regard?.questions ?? [])]))
+        o.out(`question : ${q}`);
+    return 0;
+}