@sylad/cadence 1.9.0 → 1.11.0

package/dist/ref/figures.js

@@ -11,11 +11,18 @@ const WORDS = {
     planches: { kind: 'planche', word: 'Planche' },
 };
 const NUMBER = String.raw `[A-Z]{0,2}[-.]?\d+(?:[.-](?:\d+|[A-Z](?![a-z])))*[a-z]?`;
-/** Ce qui sépare deux numéros d'une énumération au pluriel : « 2, 3 », « 2 and 3 », « 4 to 6 ». */
-const SEPARATOR = String.raw `(?:\s*,\s*(?:(?:and|et)\s+)?|\s+(?:and|et|to|à|&)\s+)`;
+/** Ce qui joint les deux bornes d'une plage : « 4 to 6 », « 4 à 6 », « 2–4 » (demi-cadratin collé aux numéros). Un tiret entouré d'espaces ou un cadratin (« 3—10 stations ») est une incise de prose. */
+const RANGE = String.raw `(?:\s+(?:to|à)\s+|–)`;
+/** Ce qui sépare deux numéros d'une énumération au pluriel : « 2, 3 », « 2 and 3 », plus les plages. */
+const SEPARATOR = String.raw `(?:\s*,\s*(?:(?:and|et)\s+)?|\s+(?:and|et|&)\s+|${RANGE})`;
 const REFERENCE = new RegExp(String.raw `\b(Figures?|Figs?|Tables?|Tableaux|Tableau|Planches?)\.?\s+(${NUMBER}(?:${SEPARATOR}${NUMBER})*)(?![\w])`, 'gi');
 const PLURAL = /^(?:figures|figs|tables|tableaux|planches)$/i;
 const NUMBER_ONLY = new RegExp(NUMBER, 'g');
+/** Ce qui précède une référence qui n'en est pas une : « code figure 3 », « indicator figures 1 to 6 » des normes OMM sont des valeurs de code, pas des figures. */
+const CODE_FIGURE = /\b(?:code|indicator)\s+$/i;
+/** « code figure 17 » plus haut dans la même phrase (la phrase finit à un point, un point-virgule ou un deux-points suivi d'un blanc) : il porte une plage au demi-cadratin (« … over figures 20–49 »). */
+const CODE_FIGURE_IN_SENTENCE = /\bcode\s+figures?\b/i;
+const SENTENCE_END = /[.;:!?]\s/;
 /** « Figure n » en début de ligne, puis le séparateur éventuel (tiret, deux-points, point) et le reste de la ligne. */
 const CAPTION = new RegExp(String.raw `^(Figure|Fig|Table|Tableau|Planche)\.?\s+(${NUMBER})(?![\w])\s*([:.–—-])?\s*(.*)$`, 'i');
 /** Le reste d'une ligne qui n'est qu'une parenthèse fermée : « (in accordance with 4.3.11) ». */
@@ -25,6 +32,37 @@ const DEICTIC = /\b(as shown (?:below|above)|shown (?:below|above)|illustrated (
 const LEADER = /\.{4,}|(?:\.\s){4,}/;
 /** Numéro de page en fin de titre d'un sommaire sans points de conduite : « Figure 1 Titre 12 » (le titre est « Titre 12 », le numéro de la figure n'en est pas un). */
 const TRAILING_PAGE = /(?:^|\s)(\d{1,4})\s*$/;
+/** Lignes courantes du document : en-têtes et pieds de page, c'est-à-dire les deux premières et les deux dernières lignes d'une page, chiffres mis à part, qui reviennent sur trois pages au moins. */
+function runningLines(pages) {
+    const normal = (text) => text.trim().replace(/\d+/g, '#');
+    const pagesOf = new Map();
+    for (const p of pages)
+        for (const t of new Set([...p.lines.slice(0, 2), ...p.lines.slice(-2)].map((l) => normal(l.text))))
+            pagesOf.set(t, (pagesOf.get(t) ?? 0) + 1);
+    return (text) => (pagesOf.get(normal(text)) ?? 0) >= 3;
+}
+/**
+ * Dernière ligne de texte avant la ligne `i` de la page `pi`, sans les lignes courantes ni les lignes vides ; elle remonte sur la page
+ * qui précède immédiatement (numéro consécutif) : « code » peut finir une page, suivi de son pied de page et de l'en-tête de la suivante.
+ */
+function precedingText(pages, pi, i, running) {
+    let page = pages[pi];
+    for (let k = pi, j = i - 1;; j--) {
+        if (j < 0) {
+            const prev = pages[k - 1];
+            if (!prev || prev.n !== page.n - 1)
+                return '';
+            page = prev;
+            k--;
+            j = prev.lines.length - 1;
+            if (j < 0)
+                continue;
+        }
+        const text = page.lines[j].text;
+        if (text.trim() !== '' && !running(text))
+            return text;
+    }
+}
 const labelOf = (word, num) => {
     const w = WORDS[word.toLowerCase()];
     return { label: `${w.word} ${num}`, kind: w.kind };
@@ -67,16 +105,41 @@ function tocLines(page, lastPage) {
     const contents = candidates >= 2 && candidates * 2 > page.lines.length;
     return leaders.map((e) => e || contents);
 }
-/** Numéros nommés par une référence : le seul numéro au singulier ; au pluriel la liste, et « 4 to 6 » donne 4, 5, 6 quand ce sont des entiers. */
+const RANGE_ONLY = new RegExp(`^${RANGE}$`, 'i');
+const named = (num) => ({ num, interior: false });
+/** Un numéro divisé en préfixe (« 1.B. », « 3- », « A- », « A ») et chiffres finaux. */
+const TRAILING_DIGITS = /^(.*\D)?(\d+)$/;
+/**
+ * Numéros d'une plage : « 4 » et « 6 » donnent 4, 5, 6 (« 01 » et « 03 » donnent 01, 02, 03 : le zéro de tête de la première borne fixe la largeur) ; « 1.1 » et « 1.3 » donnent 1.1, 1.2, 1.3, de même « 3-1 »/« 3-3 » et « A1 »/« A3 ». Les bornes sont nommées, le milieu non.
+ * Sinon les bornes seules : préfixes différents, plage décroissante, 50 numéros ou plus. Une borne nue après une borne à préfixe
+ * (« 4.8–10 », « A3–1 ») n'est pas une figure à part : seule la première est gardée.
+ */
+function expand(from, to) {
+    const a = TRAILING_DIGITS.exec(from);
+    const b = TRAILING_DIGITS.exec(to);
+    if (b && b[1] === undefined && a && a[1] !== undefined)
+        return [named(from)];
+    if (!a || !b || (a[1] ?? '') !== (b[1] ?? ''))
+        return [named(from), named(to)];
+    const [lo, hi] = [Number(a[2]), Number(b[2])];
+    if (hi < lo || hi - lo >= 50)
+        return [named(from), named(to)];
+    return Array.from({ length: hi - lo + 1 }, (_, i) => ({ num: `${a[1] ?? ''}${String(lo + i).padStart(a[2].length, '0')}`, interior: i > 0 && i < hi - lo }));
+}
+/** Numéros nommés par une référence : le seul numéro au singulier ; au pluriel la liste, chaque plage (« 4 to 6 », « 2–4 ») développée quand ses bornes le permettent. */
 function numbersOf(head, list) {
-    const nums = list.match(NUMBER_ONLY) ?? [];
+    const found = [...list.matchAll(NUMBER_ONLY)];
     if (!PLURAL.test(head))
-        return nums.slice(0, 1);
-    const range = /^(\d+)\s+(?:to|à)\s+(\d+)$/i.exec(list.trim());
-    if (range && Number(range[2]) >= Number(range[1]) && Number(range[2]) - Number(range[1]) < 50) {
-        return Array.from({ length: Number(range[2]) - Number(range[1]) + 1 }, (_, i) => String(Number(range[1]) + i));
-    }
-    return nums;
+        return found.slice(0, 1).map((m) => named(m[0]));
+    const out = [];
+    found.forEach((m, i) => {
+        const prev = found[i - 1];
+        if (prev && RANGE_ONLY.test(list.slice(prev.index + prev[0].length, m.index)))
+            out.splice(out.length - 1, 1, ...expand(prev[0], m[0]));
+        else
+            out.push(named(m[0]));
+    });
+    return out;
 }
 /**
  * Légendes, citations et liens non résolus, d'après le texte seul ; les images viennent après (`attachRegions`).
@@ -114,7 +177,8 @@ export function indexText(pages, imagePages = new Set()) {
     const figures = new Map(chosen.map((c) => [key(c.label), { label: c.label, kind: c.kind, page: c.page, line: c.line, caption: c.text, box: c.box, regions: [], citations: [] }]));
     const captionLine = new Set(chosen.map((c) => `${c.page}:${c.line}`));
     const unresolved = [];
-    for (const p of pages) {
+    const running = runningLines(pages);
+    for (const [pi, p] of pages.entries()) {
         const captions = [...figures.values()].filter((f) => f.page === p.n);
         p.lines.forEach((l, i) => {
             if (toc.get(p.n)[i])
@@ -126,12 +190,21 @@ export function indexText(pages, imagePages = new Set()) {
                 // la légende ne se cite pas elle-même
                 if (own && m.index === 0)
                     continue;
-                for (const num of numbersOf(m[1], m[2])) {
+                // « code » peut finir la ligne précédente : l'extrait PDF coupe les lignes, pas le texte
+                const head = l.text.slice(0, m.index);
+                const carried = head.trim() === '' ? `${precedingText(pages, pi, i, running)} ${head}` : head;
+                if (labelOf(m[1], '').kind === 'figure' && (CODE_FIGURE.test(carried) || (m[2].includes('–') && CODE_FIGURE_IN_SENTENCE.test(carried.split(SENTENCE_END).pop()))))
+                    continue;
+                for (const { num, interior } of numbersOf(m[1], m[2])) {
                     const { label } = labelOf(m[1], num);
+                    const fig = figures.get(key(label));
+                    // le milieu d'une plage sans légende n'est pas un lien à résoudre (« figures 11–20 » n'en désigne aucune) et ne masque pas
+                    // une citation explicite du même numéro plus loin sur la ligne
+                    if (interior && !fig)
+                        continue;
                     if (seen.has(key(label)))
                         continue;
                     seen.add(key(label));
-                    const fig = figures.get(key(label));
                     if (fig)
                         fig.citations.push({ page: p.n, line, extrait: l.text.trim(), type: 'nommee' });
                     else

package/dist/ref/pdf.js

@@ -7,8 +7,20 @@ import { RafError } from '../plan.js';
 export const DPI = 200;
 const SCALE = DPI / 72;
 const px = (pt) => Math.round(pt * SCALE);
-function exec(file, args, cwd) {
-    return execFileSync(file, args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 1024 * 1024 * 512, env: { ...process.env, LC_ALL: 'C' } });
+function exec(file, args) {
+    return execFileSync(file, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 1024 * 1024 * 512, env: { ...process.env, LC_ALL: 'C' } });
+}
+/** Lance un outil poppler ; son échec (code non nul, sortie trop grosse, sortie illisible) devient une RafError qui le nomme, avec la raison. */
+function poppler(name, tools, args, file) {
+    try {
+        return exec(tools[name], args);
+    }
+    catch (e) {
+        const err = e;
+        const reason = String(err.stderr ?? '').split('\n').find((l) => l.trim() !== '' && !/^Syntax Warning/.test(l)) ?? String(err.message ?? '').split('\n')[0] ?? '';
+        const clean = reason.replace(/^Syntax Error[^:]*: /, '').trim();
+        throw new RafError(`ref : ${name} a échoué sur ${file}${clean ? ` (${clean})` : ''}`);
+    }
 }
 /** Nombre de pages ; un PDF chiffré, abîmé ou sans page est refusé avec la raison. */
 export function pageCount(tools, file) {
@@ -33,7 +45,7 @@ const attr = (tag, name) => new RegExp(`${name}="([^"]*)"`).exec(tag)?.[1] ?? ''
 const unescapeXml = (s) => s.replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&apos;/g, "'").replace(/&amp;/g, '&');
 /** Texte positionné de tout le document (`pdftotext -bbox-layout` : mots regroupés en lignes), en pixels de la page rendue. */
 export function textLayout(tools, file) {
-    const xml = exec(tools.pdftotext, ['-bbox-layout', file, '-']);
+    const xml = poppler('pdftotext', tools, ['-bbox-layout', file, '-'], file);
     const pages = [];
     for (const chunk of xml.split('<page ').slice(1)) {
         const head = chunk.slice(0, chunk.indexOf('>'));
@@ -55,7 +67,7 @@ export function listImages(tools, file) {
     const out = [];
     const slots = new Map();
     const ranks = new Map();
-    for (const row of exec(tools.pdfimages, ['-list', file]).split('\n').slice(2)) {
+    for (const row of poppler('pdfimages', tools, ['-list', file], file).split('\n').slice(2)) {
         const c = row.trim().split(/\s+/);
         if (c.length < 5)
             continue;
@@ -74,7 +86,7 @@ export function listImages(tools, file) {
 export function renderPages(tools, file, pages, dir) {
     mkdirSync(dir, { recursive: true });
     for (const n of pages)
-        exec(tools.pdftoppm, ['-r', String(DPI), '-png', '-singlefile', '-f', String(n), '-l', String(n), file, join(dir, `page-${n}`)]);
+        poppler('pdftoppm', tools, ['-r', String(DPI), '-png', '-singlefile', '-f', String(n), '-l', String(n), file, join(dir, `page-${n}`)], file);
 }
 /** Résolution des vignettes de toutes les pages (à parcourir pour repérer les planches d'un document sans texte). */
 export const THUMB_DPI = 40;
@@ -82,19 +94,19 @@ export const THUMB_DPI = 40;
 export function renderThumbnails(tools, file, total, dir) {
     mkdirSync(dir, { recursive: true });
     for (let n = 1; n <= total; n++)
-        exec(tools.pdftoppm, ['-r', String(THUMB_DPI), '-png', '-singlefile', '-f', String(n), '-l', String(n), file, join(dir, `page-${n}`)]);
+        poppler('pdftoppm', tools, ['-r', String(THUMB_DPI), '-png', '-singlefile', '-f', String(n), '-l', String(n), file, join(dir, `page-${n}`)], file);
 }
 /** Extrait les images d'une page dans `dir/p<page>-<slot sur 3 chiffres>.png`. */
 export function extractImages(tools, file, page, dir) {
     mkdirSync(dir, { recursive: true });
-    exec(tools.pdfimages, ['-png', '-f', String(page), '-l', String(page), file, join(dir, `p${page}`)]);
+    poppler('pdfimages', tools, ['-png', '-f', String(page), '-l', String(page), file, join(dir, `p${page}`)], file);
 }
 export const imageFile = (page, slot) => `p${page}-${String(slot).padStart(3, '0')}.png`;
 /** Régions des images d'une page (ordre du document), en pixels de la page rendue : `pdftohtml -xml` au zoom 200/72. */
 export function imageRegions(tools, file, page) {
     const work = mkdtempSync(join(tmpdir(), 'cadence-ref-'));
     try {
-        exec(tools.pdftohtml, ['-xml', '-q', '-nodrm', '-zoom', String(SCALE), '-f', String(page), '-l', String(page), file, join(work, 'p')]);
+        poppler('pdftohtml', tools, ['-xml', '-q', '-nodrm', '-zoom', String(SCALE), '-f', String(page), '-l', String(page), file, join(work, 'p')], file);
         const xml = readFileSync(join(work, 'p.xml'), 'utf8');
         return [...xml.matchAll(/<image ([^>]*)\/>/g)].map((m) => ({ page, x: Number(attr(m[1], 'left')), y: Number(attr(m[1], 'top')), l: Number(attr(m[1], 'width')), h: Number(attr(m[1], 'height')) }));
     }

package/dist/ref/regard.js

@@ -0,0 +1,102 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { PACKAGE_ROOT } from '../orchestrate/snapshot.js';
+import { decodePng, encodePng } from './png.js';
+import { sessionDeRef } from './session.js';
+/** Marge (pixels de la page rendue) ajoutée de chaque côté de la zone d'un élément dans sa découpe : de quoi lire ce qui l'entoure. */
+export const MARGE_DECOUPE = 24;
+/** Sortie structurée du troisième regard : un verdict par numéro d'élément ; le programme ne retient que les verdicts valides. */
+export const REGARD_SCHEMA = {
+    type: 'object',
+    properties: {
+        decisions: {
+            type: 'array',
+            items: {
+                type: 'object',
+                properties: {
+                    numero: { type: 'integer', description: 'The number of the element in the brief.' },
+                    verdict: { type: 'string', enum: ['confirme', 'ecarte'] },
+                    raison: { type: 'string', description: 'One sentence: what the crop shows.' },
+                },
+                required: ['numero', 'verdict', 'raison'],
+                additionalProperties: false,
+            },
+        },
+        questions: { type: 'array', items: { type: 'string' }, description: 'What a human must settle.' },
+    },
+    required: ['decisions', 'questions'],
+    additionalProperties: false,
+};
+/** Découpe la zone d'un élément (marge comprise, bornée à la page) dans `crops/regard-<numero>.png` ; null quand la page n'est pas rendue ou que la zone est hors d'elle. */
+function decouper(docDir, e, numero, pages) {
+    const page = join(docDir, 'pages', `page-${e.source.page}.png`);
+    const z = e.source.zone;
+    if (!existsSync(page) || !z)
+        return null;
+    if (!pages.has(e.source.page))
+        pages.set(e.source.page, decodePng(readFileSync(page), `page ${e.source.page}`)); // une page se décode une fois, quel que soit le nombre de ses éléments
+    const r = pages.get(e.source.page);
+    const x0 = Math.max(0, z.x - MARGE_DECOUPE);
+    const y0 = Math.max(0, z.y - MARGE_DECOUPE);
+    const x1 = Math.min(r.width, z.x + z.l + MARGE_DECOUPE);
+    const y1 = Math.min(r.height, z.y + z.h + MARGE_DECOUPE);
+    if (x1 <= x0 || y1 <= y0)
+        return null;
+    const rgba = Buffer.alloc((x1 - x0) * (y1 - y0) * 4);
+    for (let y = y0; y < y1; y++)
+        r.data.copy(rgba, (y - y0) * (x1 - x0) * 4, (y * r.width + x0) * 4, (y * r.width + x1) * 4);
+    const dir = join(docDir, 'crops');
+    mkdirSync(dir, { recursive: true });
+    const file = join(dir, `regard-${numero}.png`);
+    writeFileSync(file, encodePng(x1 - x0, y1 - y0, rgba));
+    return file;
+}
+/** Ce qu'une lecture a écrit d'un élément, sans ce qui renvoie à sa propre numérotation ni à sa confiance : le troisième regard juge ce qui est dit, pas qui le dit. */
+const POSE = (e) => JSON.stringify(Object.fromEntries(Object.entries(e).filter(([k]) => !['id', 'confiance', 'cause', 'ocr', 'usage', 'ecran', 'cible', 'couvre'].includes(k))));
+/**
+ * Le troisième regard : une session de `reference-verifier` qui ne voit que les éléments d'une seule lecture et leur découpe, et dit pour chacun
+ * s'il est confirmé ou écarté. Rend une décision par élément (dans l'ordre de `seuls`) ; un verdict sans raison ou inconnu, ou un numéro
+ * hors de la liste, vaut une absence de réponse (`undefined`) ; un numéro répété garde son premier verdict. Un silence du troisième regard n'est jamais un `lu`.
+ */
+export async function troisiemeRegard(o) {
+    for (const f of existsSync(join(o.docDir, 'crops')) ? readdirSync(join(o.docDir, 'crops')) : [])
+        if (/^regard-\d+\.png$/.test(f))
+            rmSync(join(o.docDir, 'crops', f));
+    const cadence = `node ${join(PACKAGE_ROOT, 'bin', 'cadence.js')}`;
+    const pages = new Map();
+    const blocs = o.seuls.map((item, i) => {
+        const e = item.element;
+        const crop = decouper(o.docDir, e, i + 1, pages);
+        return [
+            `${i + 1}. ${POSE(e)}`,
+            `   page : ${join(o.docDir, 'pages', `page-${e.source.page}.png`)}`,
+            crop ? `   découpe : ${crop}` : '   pas de découpe : la page n\'est pas rendue ou la zone est hors d\'elle, regarde la page entière',
+        ].join('\n');
+    });
+    const brief = [
+        `Troisième regard sur le document de référence « ${o.slug} » : ${o.seuls.length} élément${o.seuls.length > 1 ? 's' : ''} qu'un seul des deux lecteurs a écrit${o.seuls.length > 1 ? 's' : ''}.`,
+        '',
+        `Dossier du document : ${o.docDir}`,
+        '',
+        ...blocs,
+        '',
+        `Pour chacun : confirme, ou ecarte, avec la raison. 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 ${o.configPath}`,
+        `Ne lis que les découpes et les pages ci-dessus ; n'écris aucun fichier.`,
+    ].join('\n');
+    const r = await sessionDeRef({ ...o, agent: 'reference-verifier', brief, schema: REGARD_SCHEMA, echec: 'la session du troisième regard a échoué' });
+    if (r.kind === 'quota')
+        return r;
+    const structured = r.structured;
+    const decisions = o.seuls.map(() => undefined);
+    for (const d of Array.isArray(structured?.decisions) ? structured.decisions : []) {
+        const i = Number(d?.numero) - 1;
+        const raison = typeof d?.raison === 'string' ? d.raison.trim() : '';
+        if (!Number.isInteger(i) || i < 0 || i >= decisions.length || decisions[i] !== undefined)
+            continue;
+        if ((d.verdict !== 'confirme' && d.verdict !== 'ecarte') || raison === '')
+            continue;
+        decisions[i] = { verdict: d.verdict, raison };
+    }
+    const questions = Array.isArray(structured?.questions) ? structured.questions.map(String) : [];
+    return { kind: 'ok', decisions, tokens: r.tokens, session: r.session, questions };
+}

package/dist/ref/session.js

@@ -0,0 +1,34 @@
+import { randomUUID } from 'node:crypto';
+import { readOrchestrateConfig } from '../config.js';
+import { journalTokens, runSession } from '../orchestrate/launch.js';
+import { sumTokens } from '../orchestrate/result.js';
+import { RafError } from '../plan.js';
+/**
+ * Une session de la chaîne `ref` hors vague (mêmes sortie JSON, schéma, relance de mise en forme et relance d'une session coupée qu'orchestrate),
+ * avec les jetons comptés comme le budget d'orchestrate : ceux de la session coupée (son journal) s'ajoutent à ceux de la relance.
+ * Un échec est une `RafError` (code 2), un quota un résultat.
+ */
+export async function sessionDeRef(o) {
+    const config = readOrchestrateConfig(o.configPath);
+    const outcome = await runSession({
+        kind: 'ref',
+        sessionId: randomUUID(),
+        brief: o.brief,
+        model: o.model,
+        effort: config.effort.review,
+        schema: o.schema,
+        agent: o.agent,
+        cwd: o.docDir,
+        wave: `ref-${o.slug}`,
+        permissionMode: config.permissionMode,
+        addDirs: [o.docDir],
+        timeoutMs: config.timeouts.work,
+    }, { claude: o.claude, agents: o.agents, onRelaunch: o.onRelaunch });
+    if (outcome.kind === 'quota')
+        return { kind: 'quota', message: outcome.message };
+    if (outcome.kind === 'failed')
+        throw new RafError(`ref analyse : ${o.echec} : ${outcome.cause}`);
+    const cut = outcome.relaunched ? journalTokens(o.claudeHome, o.docDir, outcome.relaunched.sessionId) : null;
+    const tokens = cut ? sumTokens(cut.tokens, outcome.result.tokens).counted : outcome.result.tokens.counted;
+    return { kind: 'ok', structured: outcome.result.structured, tokens, session: outcome.result.sessionId };
+}

package/dist/state.js

@@ -218,6 +218,19 @@ export function readDeliveries(dir) {
         return null;
     }
 }
+/** Classe d'une ligne écrite avant la classe [cls] (L282), déduite du libellé que `deliver` écrit lui-même ; null si le libellé n'est pas l'un des siens. */
+function classFromReason(reason) {
+    const script = /^script de livraison en échec \((?:code (\d+)|[^)]*)\)/.exec(reason);
+    if (script)
+        return script[1] === '2' ? 'refus' : 'deploiement';
+    if (/^(?:déploiement en échec|CADENCE_DEPLOYED_FILE )/.test(reason))
+        return 'deploiement';
+    if (/^(?:CI en échec|CI non terminée|gh run list en échec|aucun run CI pour ce sha)/.test(reason))
+        return 'ci';
+    if (/^vérification en échec/.test(reason))
+        return 'verification';
+    return null;
+}
 /** Les livraisons rouges de `deliveries-failed.log`, dans l'ordre du fichier ; une ligne illisible est ignorée, un fichier absent ou illisible donne aucune livraison rouge. Lecture seule : ne crée rien. */
 export function readFailedEntries(dir) {
     try {
@@ -230,9 +243,11 @@ export function readFailedEntries(dir) {
                 return [];
             let reason = m[3] ?? '';
             const c = /^\[(\w+)\] ?/.exec(reason);
-            const cls = c && FAIL_CLASSES.includes(c[1]) ? c[1] : null;
-            if (cls)
+            const written = c && FAIL_CLASSES.includes(c[1]) ? c[1] : null;
+            if (written)
                 reason = reason.slice(c[0].length);
+            // Sans [cls] écrit : le fichier n'est jamais réécrit, la classe se déduit du libellé à la lecture.
+            const cls = written ?? (c ? null : classFromReason(reason));
             return [{ day: m[1], sha: m[2] ?? '', cls, reason, tail }];
         });
     }

package/docs/deliver.md

@@ -69,7 +69,8 @@ cadence deliver              # 0 delivered and verified · 1 a step failed · 2
   This is a list of likely patterns, not a guarantee: a secret of another shape printed by a
   command can still land in the log, which stays local (`<git common dir>/cadence/`). `cadence perf` reads classes and projects from it
   ([perf](perf.md#delivery-quality-and-the-tour-header-l227)); a line written before L282
-  has no class and counts as « non classée ».
+  has no `[class]`: it is read by its wording (the one `deliver` writes itself, see
+  [perf](perf.md#delivery-quality-and-the-tour-header-l227)) and counts as « non classée » only when the wording is not recognised. The file is never rewritten.
 - Every command is killed when it exceeds its budget (CI, `deployTimeout`, what is
   left of `verifyTimeout`) and reported as "délai dépassé". Killed means the
   whole tree, followed while the command runs: every 200 ms cadence lists the
@@ -92,6 +93,20 @@ cadence deliver              # 0 delivered and verified · 1 a step failed · 2
   is still failing when the kill comes (the last listing is not trusted after
   1 second): only the command is killed, its descendants survive, and cadence
   says so once on stderr.
+  The 2 seconds are a constant of the real dependencies (`realDeps`, the `graceMs`
+  argument), injectable so that the tests measure the kill, not the load of the machine.
+  A Ctrl-C goes to the whole foreground group, so the command can die and its
+  exit be processed before the signal addressed to cadence: while followed
+  processes are still alive after the command exits, or the command itself died
+  of a termination signal (SIGINT, SIGTERM, SIGHUP, or exited 128 plus one of
+  them: a `curl` killed by the Ctrl-C), cadence waits up to
+  2 seconds more (`SIGNAL_PENDING_MS`, the `pendingMs` argument) for that signal,
+  and plays the grace above if it comes. Without it a background child that
+  ignores Ctrl-C would survive, and a second Ctrl-C would kill cadence without
+  releasing the lock. A command that leaves a daemon behind, or that exits 130
+  without any signal coming, therefore returns up to 2 seconds later. The termination listener is installed before
+  the command is spawned, so a Ctrl-C received while cadence first reads the
+  process list is handled too, not killed by the default action.
   A delay overrun and `SIGTERM` give no grace: a script's own `trap` does not
   get to finish there. The lock is held until the followed set is empty: when
   cadence dies of the signal it dies after the tree, and its stale lock, which
@@ -100,8 +115,9 @@ cadence deliver              # 0 delivered and verified · 1 a step failed · 2
   a process that leaves the tree before cadence first sees it (a daemon's
   double fork, `setsid`, `nohup … &` from a shell that exits, all within less
   than 200 ms), a process of another user that cadence may not signal (`sudo`),
-  a background process still running when the command returns normally (it is
-  neither waited for nor killed), and everything if cadence itself is killed
+  a background process still running when the command returns normally (cadence
+  waits up to 2 seconds for a signal on its way, see above, then carries on
+  without killing it), and everything if cadence itself is killed
   with `SIGKILL` (`kill -9`, the OOM killer).
   Where the process list cannot be read (no `/proc` and `ps` failing), cadence
   can only kill the root command (`sh`): it leads no group of its own, since it
@@ -149,7 +165,7 @@ cadence deliver --sha 6b0d9aa -- api                                  # an earli
 ```
 
 `--sha` (any mode) delivers a pushed commit other than `HEAD` — for a CI that
-builds each service only on the commit that touched it. `allowDirty` suits a
+builds each service only on the commit that touched it. To deliver an earlier commit while `HEAD` holds work that must not ship, push that sha alone first (`git push origin <sha>:main`), then `cadence deliver --dry-run --sha <sha>` and `cadence deliver --sha <sha>`: with `ci: github` the wait is for the run of that exact sha, and GitHub only builds the tip of a push (L334, the `deliver` skill says so). The push goes to the branch delivered (`main` here); skip it when the sha is already on a remote branch, and when it is refused as non-fast-forward never force it (that would rewind the remote branch): the sha is not deliverable that way, stop and ask. `allowDirty` suits a
 working tree shared by several sessions when the delivery starts from a pushed
 sha and never from local files; without it a modified tree is refused. `--sha`
 itself never reads the working tree: a tracked file modified outside the delivered

package/docs/fonctionnement.md

@@ -25,7 +25,7 @@ while a sub-task is open. A delivery is finished only when its effect checks pas
   <img alt="A lot without commits whose title cites a finding or another lot starts with a precheck (unless disabled), then by type through spec, mockup or sheet review and sealed acceptance tests, or straight to the implementation; then the UX pass if visible, the code review, corrections and an automatic raf review" src="fonctionnement-wave-light.svg">
 </picture>
 
-A lot without commits yet whose title cites a finding (`constat`, `revue`, `review`, `audit`) or another lot (its `goal:` counts like its title) starts with the **precheck** (unless `orchestrate.precheck: false`; a lot that already has commits, or whose title (or `goal:`) cites neither, is never pre-checked — L288): is the deliverable already there? « Yes » hands the lot back
+A lot without commits yet whose title cites a finding (`constat`, `revue`, `review`, `audit`) or another lot (its `goal:` counts like its title) starts with the **precheck** (unless `orchestrate.precheck: false`; a lot that already has commits, or whose title (or `goal:`) cites neither, is never pre-checked — L288; nor is a lot created after the last code commit of the repository whose title and `goal:` cite no lot that already has commits of its own, which has nothing to find — L322): is the deliverable already there? « Yes » hands the lot back
 to the lead; « partial » passes what exists to the implementation. Then:
 
 - `screen: page` only: **spec** (mockup and screen sheet), **mockup review** (`ux-reviewer`, two
@@ -73,7 +73,7 @@ working repository's `dist/`: they read a separate worktree under `~/.local/shar
 only by `npm run service -- <sha>`. The command refuses a sha that is not an ancestor of `HEAD` and a
 sha whose cited lots are not `done`, so a wave cannot put unreviewed code in service. In the
 working repository, `npm run build` is a typecheck only. A `dropped` lot whose every commit is undone
-by a `git revert` under the sha no longer blocks.
+by a `git revert` under the sha no longer blocks. The command keeps the copy in service and the 3 put in service before it (rollback), removes the older ones unless a live process still uses one, and says what it purged (number of copies, space freed).
 
 ## Budget of a lot
 
@@ -96,7 +96,7 @@ The final review is always played; the budget bounds the writing passes. A `scre
 
 - **Session cap.** As many sessions or subagents running at once as the cap (2 by default, set by the
   human with `CADENCE_MAX_SESSIONS` or `--max-sessions`). The lead never raises it itself.
-- Never two sessions in the same repository at the same time. (An experimental worktree mode, `orchestrate.worktrees: true`, would let two independent lots of one repository play at once; it is refused without `CADENCE_EXPERIMENTAL_WORKTREES=1`, lots L299–L301 to do before it is enabled — [docs/orchestrate.md](orchestrate.md#one-worktree-per-lot-orchestrateworktrees-l279).)
+- Never two sessions in the same repository at the same time. (The worktree mode, `orchestrate.worktrees: true` — on in cadence's own `cadence.yaml`, off where the key is absent — lets two independent lots of one repository play at once, each in its own worktree — [docs/orchestrate.md](orchestrate.md#one-worktree-per-lot-orchestrateworktrees-l279).)
 - A session cannot ask the human anything: it stops and reports, and the lead brings the question back.
 - A sealed acceptance test that contradicts its sheet is corrected by the lead with
   `cadence spec reseal <lot> <test> --reason "…"`, never by editing `acceptation.json`.

package/docs/lead.md

@@ -53,7 +53,9 @@ picture, not its source.
 3. **Relay.** The lead follows the wave's journal (`tail -n +1 -F .cadence/runs/<id>/journal.log`, one
    line per transition) and tells the human each line in one sentence, with no polling loop. A
    question from a session comes back to the human at once; the answer goes in with
-   `cadence orchestrate --resume --answer <project>:<lot> "…"`. The lead never answers in the
+   `cadence orchestrate --resume --wave <wave> --answer <project>:<lot> "…"` (the wave is named: the
+   command is printed under each question of the table, ready to run; without a wave, `--resume` is refused as
+   soon as the folder keeps several unfinished waves). The lead never answers in the
    human's place. `--drop` and `--stop-after-current` steer a wave that is running.
 4. **Review.** The final table of the wave lists the lots ready, handed back, and the line
    « livrable jusqu'à <sha> » for a ready lot stacked under a handed-back one. Minor findings come back in
@@ -81,8 +83,8 @@ picture, not its source.
 | Rule | Why |
 |---|---|
 | At most **as many subagents as the session cap** running at once (2 by default; the human sets it with `CADENCE_MAX_SESSIONS`), orchestrate sessions included | `cadence orchestrate --status` and `cadence lead tour` print `créneaux libres : N sur M`, M being the configured cap and the sessions the lead started by hand (`cadence lead hold`, L255) being subtracted; the lead never raises `--max-sessions` or `CADENCE_MAX_SESSIONS` itself |
-| Never two sessions in the same repository at the same time; the lead does not commit where a wave runs (the experimental worktree mode, `orchestrate.worktrees: true`, is refused without `CADENCE_EXPERIMENTAL_WORKTREES=1` until L299–L301 are done: not a rule for the lead) | a wave's lock refuses `cadence deliver` while a lot still works there |
-| A locked acceptance test that contradicts the sheet is corrected by the lead with `cadence spec reseal <lot> <test> --reason "…"` (lot in progress, outside a wave and with no wave that is not `done` keeping open a lot of the repository still `doing` in its plan, the resealed lot or another, e.g. a question waiting: `--resume --answer` or `--drop` first, the one error lists every wave concerned, the live one that holds the lock (to wait for) and the stopped ones, and gives for each stopped wave the single `cd <launch folder> && cadence orchestrate --resume <wave> --drop <project>:<lot> [--drop …]` to run, a `--drop` per open lot of the repository in that wave, the queued ones that are not `doing` in the plan included, since `--resume` would relaunch them and they would take the lock back, L238 L239; an amended sheet is accepted once committed, every commit that touched it citing the lot, L217, never put it back to the red state; a delivered lot with an unstable test: add `--porteur <lot in progress>`, L212), then a new `cadence orchestrate <project>:<lot>` for a lot handed back (`--resume` skips it) | never by a session, never by editing `acceptation.json` |
+| Never two sessions in the same repository at the same time; the lead does not commit where a wave runs (with `orchestrate.worktrees: true` two lots of one repository play at once, each in its own worktree: not a rule for the lead) | a wave's lock refuses `cadence deliver` while a lot still works there |
+| A locked acceptance test that contradicts the sheet is corrected by the lead with `cadence spec reseal <lot> <test> --reason "…"` (lot in progress, outside a wave and with no wave that is not `done` keeping open a lot of the repository still `doing` in its plan, the resealed lot or another, e.g. a question waiting: `--resume --wave <wave> --answer` or `--drop` first, the one error lists every wave concerned, the live one that holds the lock (to wait for) and the stopped ones, and gives for each stopped wave the single `cd <launch folder> && cadence orchestrate --resume --wave <wave> --drop <project>:<lot> [--drop …]` to run, a `--drop` per open lot of the repository in that wave, the queued ones that are not `doing` in the plan included, since `--resume` would relaunch them and they would take the lock back, L238 L239; an amended sheet is accepted once committed, every commit that touched it citing the lot, L217, never put it back to the red state; a delivered lot with an unstable test: add `--porteur <lot in progress>`, L212), then a new `cadence orchestrate <project>:<lot>` for a lot handed back (`--resume` skips it) | never by a session, never by editing `acceptation.json` |
 | Deliveries and the `raf ux` / `raf review` verdicts belong to the lead, one project at a time | never to a subagent, never two deliveries in parallel |
 | The UX verdict is the human's unless `lead.ux: lead` (parent `cadence.yaml`, default `human`) | then the lead decides from the report and the captures, and brings any doubt to the human |
 | A session cannot ask the human anything | it stops and reports; the lead brings the question back |
@@ -145,7 +147,9 @@ beta · en cours rien · dérive aucune · notes : aucune · prochain T2 Second
 | `attend` | only when a lot waits on its `gate`: `attend L190` |
 | `dépôt` | `non commité` (modified or untracked files), `non poussé` (commits ahead of the upstream), `livraison en cours` (live delivery lock); `propre` otherwise |
 
-After the project lines the tour lists the **worktrees kept by waves** (L279, experimental mode, not enabled until L299–L301 are done; [`orchestrate.worktrees`](orchestrate.md#one-worktree-per-lot-orchestrateworktrees-l279)): a title, then one line per kept worktree — repository, lot, age, number of unintegrated commits, path — so that a lot handed back with unintegrated commits is never forgotten; nothing is printed when there is none (`--json`: `worktrees` on the project's row). `cadence orchestrate --status` and the final table of a wave print the same lines; the lead removes one with `cadence orchestrate --remove-worktree <project>:<lot> [--abandon-commits]`.
+After them, one line per project that does not declare `orchestrate.test` (L327): `alpha · porte de tests absente : orchestrate.test n'est pas déclaré, la vague ne lancera pas la suite (seule la revue le fera si elle le décide) · commande probable : npm test (à déclarer en orchestrate.test)`. The probable command is read from `package.json` (`scripts.test`), `pyproject.toml` (pytest) or `pom.xml` (`mvn test`) and omitted when none exists; the lead declares `test:` and `build:` in that project's `cadence.yaml` after checking the command is green, one config commit per project. `--json`: `noTest: { probable }` on the project's row, absent when the key is declared. Same line in [`orchestrate --dry-run`](orchestrate.md).
+
+After the project lines the tour lists the **worktrees kept by waves** (L279, `orchestrate.worktrees: true`, on by default in cadence since L320; [`orchestrate.worktrees`](orchestrate.md#one-worktree-per-lot-orchestrateworktrees-l279)): a title, then one line per kept worktree — repository, lot, age, number of unintegrated commits, path — so that a lot handed back with unintegrated commits is never forgotten; nothing is printed when there is none (`--json`: `worktrees` on the project's row). `cadence orchestrate --status` and the final table of a wave print the same lines; the lead removes one with `cadence orchestrate --remove-worktree <project>:<lot> [--abandon-commits]`.
 
 Before the project lines the tour prints the **perf header** (L227): one line per `⚠` of `cadence perf` for the folder, in the order of `perf`, each ending with its decision and, for a trend, the value of its quality twin (speed and quality side by side); the net-bottleneck `⚠ goulot` line is relayed as is. Nothing is printed when no `⚠` stands, and the output is then the one of a tour without header. The header is read with `perf`'s own reading of the folder (projects up to two levels, whatever `--depth`) and only in the text output: `--json` is unchanged. When `perf` cannot read the folder (no `.cadence/runs`, malformed price grid, unreadable journals or plans) the tour prints no header, reports no perf error and exits 0. The [lead skill](skills.md) reads the header before proposing the three lots and opens an improvement lot only on a trend confirmed on two windows or a net bottleneck.
 

package/docs/news.md

@@ -150,6 +150,8 @@ to be reported as one **major** finding per line — a stale document is not lef
 memory of a sentence. Touching a document is what the program checks; whether its text is true is
 still the review's reading. The commits of neighbouring repositories (`repos:`) are not audited.
 
+A gap is closed by writing the document, or **acknowledged** when the documents really stay true: `raf docs-ok <lot> --reason "why"` (L317; the reason is required) writes a dated `docs_ok:` key on the lot, which `raf check`, `cadence lead tour` and `cadence orchestrate` all read. There is no silent third way: a lot with an open gap does not end ready in a wave.
+
 ### The librarian: `doc-keeper`
 
 `docs.sync` says *that* a document is behind; the `doc-keeper` agent (L306, `agents/doc-keeper.md`, generic: it knows no
@@ -162,6 +164,10 @@ out, then:
 - **read-only session** (no write tool, or a brief that says so): changes nothing and lists, document by document, the
   passage to write.
 
+**Where it writes** (L326): a lot that changes how the tool works is written in the pages of `docs/`, in full.
+The README is a short home page: it receives only a link to that page, never the detail (an option, a key, a path, a flag).
+The test `readme-accueil` holds the README to that (size, short lines, no detailed option).
+
 `cadence orchestrate` calls it by itself when `docs.sync` reports a document behind the commits of the lot, **before the
 review** (see « Librarian before the review » in [orchestrate](orchestrate.md)); the lead calls it by hand otherwise
 ([lead](lead.md)).