@sylad/cadence 1.8.0 → 1.10.0

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/ref/store.js

@@ -0,0 +1,40 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { readReferencesConfig } from '../config.js';
+import { gitRoot } from '../git.js';
+import { RafError } from '../plan.js';
+/**
+ * Dossier des documents : `references.dir` de cadence.yaml (relatif à son dossier), sinon `$XDG_DATA_HOME/cadence/references`.
+ * Un `references.dir` dans un dépôt Git est refusé : les documents de référence peuvent être privés, ils ne se commitent pas.
+ */
+export function referencesDir(root, configPath, env) {
+    const dir = readReferencesConfig(configPath).dir;
+    if (dir === undefined)
+        return join(env.XDG_DATA_HOME || join(env.HOME || homedir(), '.local', 'share'), 'cadence', 'references');
+    const abs = resolve(dirname(configPath), dir);
+    let probe = abs;
+    while (!existsSync(probe) && dirname(probe) !== probe)
+        probe = dirname(probe);
+    if (gitRoot(probe))
+        throw new RafError(`ref : references.dir (${abs}) est dans un dépôt Git : les documents de référence restent hors du dépôt (choisir un dossier ailleurs, ou retirer la clé pour $XDG_DATA_HOME/cadence/references)`);
+    return abs;
+}
+export const documentFile = (docDir) => join(docDir, 'document.json');
+export function readDocument(docDir) {
+    const file = documentFile(docDir);
+    if (!existsSync(file))
+        return null;
+    try {
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch (e) {
+        throw new RafError(`ref : ${file} illisible : ${e.message.split('\n')[0]}`);
+    }
+}
+export function writeDocument(docDir, doc) {
+    mkdirSync(docDir, { recursive: true });
+    const tmp = `${documentFile(docDir)}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(doc, null, 2)}\n`);
+    renameSync(tmp, documentFile(docDir));
+}

package/dist/ref/tools.js

@@ -0,0 +1,51 @@
+import { accessSync, constants, statSync } from 'node:fs';
+import { delimiter, join } from 'node:path';
+import { RafError } from '../plan.js';
+const POPPLER = 'sudo apt install poppler-utils';
+/** Les outils du système dont `cadence ref` dépend, dans l'ordre où l'erreur les nomme. */
+export const TOOLS = [
+    { name: 'pdftoppm', commands: ['pdftoppm'], install: POPPLER },
+    { name: 'pdftotext', commands: ['pdftotext'], install: POPPLER },
+    { name: 'pdfimages', commands: ['pdfimages'], install: POPPLER },
+    { name: 'pdfinfo', commands: ['pdfinfo'], install: POPPLER },
+    { name: 'pdftohtml', commands: ['pdftohtml'], install: POPPLER },
+    { name: 'magick', commands: ['magick', 'convert'], install: 'sudo apt install imagemagick' },
+    { name: 'tesseract', commands: ['tesseract'], install: 'sudo apt install tesseract-ocr' },
+];
+function executable(file) {
+    try {
+        if (!statSync(file).isFile())
+            return false;
+        accessSync(file, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function which(command, path) {
+    for (const dir of path.split(delimiter)) {
+        if (dir && executable(join(dir, command)))
+            return join(dir, command);
+    }
+    return null;
+}
+/**
+ * Chemin absolu de chaque outil, cherché dans le PATH de l'environnement de la commande. Un outil absent est nommé avec sa
+ * commande d'installation (une ligne par outil), la commande sort en 2 : rien n'est installé d'office.
+ */
+export function requireTools(env) {
+    const path = env.PATH ?? '';
+    const found = {};
+    const missing = [];
+    for (const t of TOOLS) {
+        const hit = t.commands.map((c) => which(c, path)).find((p) => p !== null);
+        if (hit)
+            found[t.name] = hit;
+        else
+            missing.push(`  ${t.commands.join(' ou ')} : ${t.install}`);
+    }
+    if (missing.length > 0)
+        throw new RafError(`ref : outil absent du PATH, à installer (rien n'est installé d'office) :\n${missing.join('\n')}`);
+    return found;
+}

package/dist/resources.js

@@ -0,0 +1,51 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { parse } from 'yaml';
+import { isOpen, RafError, RESOURCE_NAME, RESOURCES_BAD_LIST } from './plan.js';
+/**
+ * Clé `resources:` du cadence.yaml le plus proche en remontant depuis le dossier parent de `root` : le premier fichier qui porte la clé
+ * (même vide) l'emporte. Aucun ne la porte : liste vide, attribuée au cadence.yaml du parent direct. Un fichier illisible ou une clé
+ * qui n'est pas une liste de noms valides est une `RafError` nommant le fichier, jamais une liste vide silencieuse.
+ */
+export function readResources(root) {
+    const fallback = join(dirname(root), 'cadence.yaml');
+    for (let dir = dirname(root);; dir = dirname(dir)) {
+        const file = join(dir, 'cadence.yaml');
+        if (existsSync(file) && statSync(file).isFile()) {
+            let raw;
+            try {
+                raw = parse(readFileSync(file, 'utf8'));
+            }
+            catch (e) {
+                throw new RafError(`${file} illisible : ${e.message.split('\n')[0]}`);
+            }
+            if (raw != null && typeof raw === 'object' && Object.hasOwn(raw, 'resources')) {
+                const list = raw.resources ?? [];
+                if (!Array.isArray(list) || !list.every((n) => typeof n === 'string' && RESOURCE_NAME.test(n)))
+                    throw new RafError(`${file} : resources ${RESOURCES_BAD_LIST}`);
+                return { file, names: [...new Set(list)] };
+            }
+        }
+        if (dirname(dir) === dir)
+            return { file: fallback, names: [] };
+    }
+}
+/**
+ * Un écart par ressource d'un lot ouvert que le cadence.yaml des dossiers parents ne déclare pas. Le fichier n'est lu que si un lot ouvert
+ * porte `uses:` : un plan qui n'en porte pas donne le contrôle d'avant, quel que soit l'état du dossier parent.
+ */
+export function resourceIssues(lots, root) {
+    const using = lots.filter((l) => isOpen(l.status) && l.uses?.length);
+    if (using.length === 0)
+        return [];
+    let declared;
+    try {
+        declared = readResources(root);
+    }
+    catch (e) {
+        if (e instanceof RafError)
+            return [{ message: e.message }];
+        throw e;
+    }
+    return using.flatMap((l) => l.uses.filter((n) => !declared.names.includes(n)).map((n) => ({ message: `${l.id} utilise la ressource « ${n} », non déclarée dans ${declared.file} (resources:)` })));
+}

package/dist/session.js

@@ -81,6 +81,8 @@ export function lastActivity(lot, commits) {
     const days = [commits[0]?.day, lot.started, ...lot.notes.map((n) => n.date)].filter((d) => !!d);
     return days.length ? days.reduce(maxDay) : undefined;
 }
+/** « 0 commit », « 1 commit », « 3 commits » : le zéro se dit, une note de clôture sur un lot sans commit ne se lit pas comme « fini ». */
+export const commitCount = (n) => `${n} commit${n > 1 ? 's' : ''}`;
 const hhmm = (d) => `${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}`;
 /**
  * Fenêtre de la clôture : --since s'il est donné ; sinon depuis la dernière ouverture du
@@ -114,10 +116,11 @@ export function sessionStart(ctx, opts) {
     if (doing.length === 0)
         out('  (rien)');
     for (const l of doing) {
-        const last = lastActivity(l, all.byLot.get(l.id) ?? []);
+        const commits = all.byLot.get(l.id) ?? [];
+        const last = lastActivity(l, commits);
         const idle = last ? diffDays(last, today) : 0;
         const state = last ? `dernière activité ${last}${idle > opts.idle ? `, silencieux depuis ${idle} j` : ''}` : 'aucune activité';
-        out(`  ${l.id}  ${l.title}  (${state})`);
+        out(`  ${l.id}  ${l.title}  (${commitCount(commits.length)}, ${state})`);
     }
     section(out, 'En attente', gateWaiting(lots, blocked).map(({ lot, text }) => `${lot.id}  ${lot.title}  (${text})`));
     const recent = period(ctx, opts.since);

package/dist/state.js

@@ -156,9 +156,48 @@ export function pidAlive(pid) {
 export function appendDelivery(dir, day, sha) {
     appendFileSync(join(dir, 'deliveries.log'), `${day} ${sha}\n`);
 }
-/** Ajoute une livraison rouge (« jour sha raison ») à `deliveries-failed.log` ; la raison est la première ligne du message d'échec. */
-export function appendFailedDelivery(dir, day, sha, reason) {
-    appendFileSync(join(dir, 'deliveries-failed.log'), `${day} ${sha} ${reason.split('\n')[0].trim()}\n`);
+/** Classe d'une livraison rouge : où elle a cassé. `refus` : le script a refusé avant d'agir (code 2). */
+export const FAIL_CLASSES = ['refus', 'ci', 'deploiement', 'verification'];
+const TAIL_SEP = ' ⏎ ';
+const TAIL_LINES = 5;
+const LINE_MAX = 200;
+const REASON_MAX = 300;
+// eslint-disable-next-line no-control-regex
+const ANSI = /\u001b\[[0-9;?]*[ -/]*[@-~]/g;
+// eslint-disable-next-line no-control-regex
+const CONTROL = /[\u0000-\u001f\u007f]/g;
+const MASK = '***';
+const SECRET_WORDS = new Set(['token', 'secret', 'password', 'passwd', 'pwd', 'pass', 'key', 'credential', 'credentials', 'auth', 'authorization', 'signature', 'sig', 'jwt', 'cookie']);
+// Mots sensibles qui, collés à un autre (APIKEY, ACCESSTOKEN, GITHUBTOKEN), terminent encore un nom : pas « pass », « sig » ou « auth » (BYPASS, ...).
+const SECRET_SUFFIXES = ['token', 'secret', 'password', 'passwd', 'key', 'credential', 'credentials', 'signature', 'pwd'];
+// Un nom de variable ou de paramètre d'URL est sensible quand l'un de ses mots (séparés par _ - . ou une majuscule) en est un, ou finit par l'un des suffixes.
+const sensitiveName = (name) => name
+    .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+    .split(/[_.-]/)
+    .some((w) => SECRET_WORDS.has(w.toLowerCase()) || SECRET_SUFFIXES.some((x) => w.toLowerCase().endsWith(x)));
+const TOKEN_SHAPES = /\b(?:gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|glpat-[A-Za-z0-9_-]{16,}|sk-[A-Za-z0-9_-]{16,}|xox[abprs]-[A-Za-z0-9-]{10,}|AKIA[0-9A-Z]{16}|npm_[A-Za-z0-9]{30,})\b/g;
+const BEARER = /\b(Bearer|Basic)\s+[A-Za-z0-9._~+/=-]{8,}/gi;
+const URL_USERINFO = /(\b[a-z][a-z0-9+.-]*:\/\/)[^\s/@]+@/gi;
+const ASSIGNMENT = /([A-Za-z][A-Za-z0-9_.-]*)=("[^"]*"|'[^']*'|[^\s&"']+)/g;
+/** Masque ce qui ressemble à un secret (jeton connu, Bearer, identifiants d'URL, VAR=valeur ou paramètre d'URL au nom sensible) : motifs probables, pas une garantie. */
+export const maskSecrets = (line) => line
+    .replace(BEARER, `$1 ${MASK}`)
+    .replace(URL_USERINFO, `$1${MASK}@`)
+    .replace(TOKEN_SHAPES, MASK)
+    .replace(ASSIGNMENT, (m, name) => (sensitiveName(name) ? `${name}=${MASK}` : m));
+const clean = (line, max) => {
+    const t = maskSecrets(line.replace(ANSI, '').replace(CONTROL, ' ')).replaceAll('⏎', ' ').trim();
+    return t.length > max ? `${t.slice(0, max - 1)}…` : t;
+};
+/**
+ * Ajoute une livraison rouge à `deliveries-failed.log` : une ligne « jour sha [classe] raison ⏎ ligne ⏎ ligne ».
+ * La raison est la première ligne du message d'échec ; `tail` (sortie de la commande en échec) est borné à ses
+ * 5 dernières lignes non vides de 200 caractères, sans séquence ANSI, secrets probables masqués (raison comprise).
+ */
+export function appendFailedDelivery(dir, day, sha, reason, cls, tail = []) {
+    const kept = tail.flatMap((l) => clean(l, LINE_MAX) || []).slice(-TAIL_LINES);
+    const head = `${day} ${sha} ${cls ? `[${cls}] ` : ''}${clean(reason.split('\n')[0], REASON_MAX)}`;
+    appendFileSync(join(dir, 'deliveries-failed.log'), `${[head, ...kept].join(TAIL_SEP)}\n`);
 }
 export function lastDelivery(dir) {
     const file = join(dir, 'deliveries.log');
@@ -179,15 +218,44 @@ export function readDeliveries(dir) {
         return null;
     }
 }
-/** Les jours de `deliveries-failed.log` (une ligne « jour sha raison » par livraison rouge), 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 readFailedDeliveries(dir) {
+/** 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 {
         return readFileSync(join(dir, 'deliveries-failed.log'), 'utf8')
             .split('\n')
-            .map((l) => l.split(' ')[0])
-            .filter(isDay);
+            .flatMap((line) => {
+            const [head = '', ...tail] = line.split(TAIL_SEP);
+            const m = /^(\S+)(?: (\S+))?(?: (.*))?$/.exec(head);
+            if (!m || !isDay(m[1]))
+                return [];
+            let reason = m[3] ?? '';
+            const c = /^\[(\w+)\] ?/.exec(reason);
+            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 }];
+        });
     }
     catch {
         return [];
     }
 }
+/** Les jours de `deliveries-failed.log` (une ligne par livraison rouge), dans l'ordre du fichier. */
+export function readFailedDeliveries(dir) {
+    return readFailedEntries(dir).map((e) => e.day);
+}

package/dist/testgate.js

@@ -0,0 +1,15 @@
+import { docSyncSet } from './docsync.js';
+export const DEFAULT_TEST_PATTERNS = ['**/*.test.*', '**/*.spec.*', 'test/**', 'tests/**', '**/__tests__/**'];
+/**
+ * Les fichiers de code que le lot a modifiés sans toucher le moindre fichier de test (triés), ou rien : un test touché, ou
+ * moins de `threshold` fichiers de code. Un fichier de test n'est jamais du code, même quand il correspond à `code`.
+ */
+export function testGateMissing(gate, files) {
+    const isTest = docSyncSet(gate.tests);
+    if ([...files].some(isTest))
+        return [];
+    const isCode = docSyncSet(gate.code);
+    const isException = gate.except.length ? docSyncSet(gate.except) : () => false;
+    const code = [...files].filter((f) => isCode(f) && !isException(f)).sort();
+    return code.length >= gate.threshold ? code : [];
+}

package/docs/cadence-hud.md

@@ -27,6 +27,18 @@ ol      ▮▮▮▮▮▯▯▯▯▯ 39/78 · 0 en cours · +3 cette semaine
 cadence ▮▮▮▮▮▯▯▯▯▯ 10/20 · 2 en cours : L149 L153
 ```
 
+The **sessions of the lead** (L276) — the ones started by hand and declared with `cadence lead hold <label>` — are drawn
+under the waves, even when no wave is running: the slots line of `cadence orchestrate --status` and one line per session
+(label, age, time left):
+
+```
+sessions du lead : 1 · créneaux libres : 2 sur 3
+  correctif-L12  depuis 4 min · reste 56 min
+```
+
+With a live wave and no held session the line reads `créneaux libres : 1 sur 2`; with neither, nothing. A session whose
+time limit has run out stops counting in the slots but is not dropped (L278): a row `⚠ session du lead échue : correctif-B28  échue depuis 2 h 10` stays under the others (in red) until `cadence lead release <label>` or a renewed `lead hold`, since nothing stops the session itself. They are read from disk (`holds/` of the cadence home), like the waves.
+
 The bar is lots done over lots done + in progress + to do (dropped and recurring lots left out); the count of lots in progress is followed by their ids (`2 en cours : L149 L153`), cut to three then `…` (`5 en cours : L1 L2 L3 …`), the count alone at zero;
 `+N cette semaine` counts the lots created in the last 7 days (today and the six before) and is left out at zero. The source is
 `cadence lead tour <folder> --json` (the folder a wave was launched from, otherwise the session's: a folder of projects gives one line per project, a project with no sub-project gives its own single line),

package/docs/cycle-vague-dark.svg

@@ -38,5 +38,5 @@
 <line x1="981" y1="127" x2="981" y2="68" stroke="#58a6ff" stroke-width="1.2" stroke-dasharray="3 3" marker-end="url(#a)"/>
 <text x="73" y="216" font-size="11.5" fill="#8b949e">dashed: only for a lot with a page or a behaviour to pin down (screen: page, spec: true)</text>
 <text x="661" y="216" font-size="11.5" fill="#8b949e">each step in a fresh session, driven by cadence orchestrate</text>
-<text x="20" y="236" font-size="11.5" fill="#8b949e">Every verdict is written to the plan (docs/plan/raf.yaml); a delivery counts only when its checks pass.</text>
+<text x="20" y="236" font-size="11.5" fill="#8b949e">Every verdict is written to the plan (.cadence/raf.yaml); a delivery counts only when its checks pass.</text>
 </svg>

package/docs/cycle-vague-light.svg

@@ -38,5 +38,5 @@
 <line x1="981" y1="127" x2="981" y2="68" stroke="#0969da" stroke-width="1.2" stroke-dasharray="3 3" marker-end="url(#a)"/>
 <text x="73" y="216" font-size="11.5" fill="#57606a">dashed: only for a lot with a page or a behaviour to pin down (screen: page, spec: true)</text>
 <text x="661" y="216" font-size="11.5" fill="#57606a">each step in a fresh session, driven by cadence orchestrate</text>
-<text x="20" y="236" font-size="11.5" fill="#57606a">Every verdict is written to the plan (docs/plan/raf.yaml); a delivery counts only when its checks pass.</text>
+<text x="20" y="236" font-size="11.5" fill="#57606a">Every verdict is written to the plan (.cadence/raf.yaml); a delivery counts only when its checks pass.</text>
 </svg>

package/docs/deliver.md

@@ -43,6 +43,34 @@ cadence deliver              # 0 delivered and verified · 1 a step failed · 2
   CI can only build what was pushed); no other delivery running (a lock whose
   process died is removed with a warning); with `ci: github`, `gh` installed and
   logged in.
+- **Red delivery log** (L282): a failure after the lock is taken appends one line to
+  `<git common dir>/cadence/deliveries-failed.log`: `day sha [class] reason ⏎ line ⏎ line`.
+  The class says where it broke: `refus` (the project script exited with code 2 — the
+  convention of `deliver` itself for « refused before acting »), `ci`, `deploiement`
+  (the project script with any other code, a deploy command, an unusable
+  `CADENCE_DEPLOYED_FILE`) or `verification`. The reason is the first line of the failure
+  message, followed by the **last 5 non-empty lines** (200 characters each, ANSI sequences
+  removed) of the output of the command that failed: the project script, the CI command, the
+  deploy command or the check command. A GitHub CI run or an URL check has no output of its
+  own, so no line follows. cadence now relays the output of those commands through itself
+  (same bytes on its own stdout and stderr, but the command no longer sees a terminal there,
+  so it may drop colours or progress bars). A line rewritten with `\r` (a progress bar that
+  did not drop) keeps only its last non-empty frame, not 5 frames of the bar. **Probable
+  secrets are masked** (`***`) in the reason and in those lines before the file is written:
+  known token shapes (GitHub, GitLab, npm, Slack, AWS key id, `sk-…`), `Bearer`/`Basic`
+  values, `user:password@` in a URL, and any `NAME=value` (shell variable or URL query
+  parameter) whose name has a word such as token, secret, password, key, auth, signature, or
+  ends with one of token, secret, password, pwd, key, credential, signature (`APIKEY`,
+  `ACCESSTOKEN`, `GITHUBTOKEN`, `MYSQLPWD`) (L294). The 8192 characters kept are the END of the
+  output (`OUTPUT_KEPT`, `src/deliver.ts`), so the bound cannot cut the end of a value; it can cut
+  its beginning (the name and the opening quote gone), and that case is **not handled** — the log
+  stays local. A quoted value never closed is not treated either (L294 tried, and each fix opened a
+  new leak): only closed values and unquoted values are matched.
+  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]`: 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
@@ -65,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
@@ -73,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
@@ -90,7 +133,7 @@ cadence deliver              # 0 delivered and verified · 1 a step failed · 2
   5 minutes is a failure (you probably pushed another commit than the one you
   deliver); every run must end `success`, `skipped` or `neutral`. `gh` errors
   are retried, and reported with their cause after 5 minutes.
-- Commands get `CADENCE_SHA`, `CADENCE_SHORT` (7 characters) and `CADENCE_BRANCH`;
+- Commands get `CADENCE_SHA`, `CADENCE_SHORT` (7 characters) and `CADENCE_BRANCH` (a `deliver.script` also gets `CADENCE_DEPLOYED_FILE`, see below);
   `${SHA}` and `${SHORT}` are replaced in `url` and `contains`.
 - On success the lots cited by the commits since the previous delivery are
   listed, so you can `raf done` those whose effect you have seen. With a
@@ -124,13 +167,41 @@ 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
 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 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
+sha (the plan after `raf done`, say) neither refuses nor is reported, with or
+without `allowDirty`.
+
+**While a wave runs.** `cadence orchestrate` holds the repository: a plain `cadence deliver` is refused until every lot of the
+repository in the wave is ready or handed back. `--sha` is the exception (L277): it is accepted while the wave runs when no
+commit in the history of `<sha>` belongs to a lot of the wave that is not ready (running, queued, in question, suspended,
+handed back, failed), that is when `<sha>` is « livrable jusqu'à » (the line the wave's final table prints). A ready lot is
+then delivered while the wave runs, without waiting for the slowest lot. The refusal names the lots that hold the sha back. A lot's commits
+are what git attributes to it in the repository (the commits that cite it) **and** what its sessions' reports noted, for the project's own
+repository as for a neighbour one (the lot's `repos:` key): git sees at once the commit of a session still running, cut by the quota or failed,
+which the reports only note when the session ends validly. A lot of the wave with no commit yet blocks nothing. What cannot be verified is
+refused: an unreadable wave state, an unknown sha, or a lot that is not ready whose commits cannot be read (its project's plan is unreadable or
+does not know the lot) while none of the commits already known holds the sha back. Push the sha alone first (`git push origin <sha>:main`).
+
+**What is logged as delivered.** cadence no longer guesses which commit a project script deployed. Before running `deliver.script` it creates an
+empty file and hands its path to the script in `CADENCE_DEPLOYED_FILE` (next to `CADENCE_SHA`, `CADENCE_SHORT`, `CADENCE_BRANCH`). A script
+that deploys a commit other than `CADENCE_SHA` (it committed a `--news` timestamp itself, say) writes that sha into the file. After the script:
+
+- the file holds a hexadecimal sha (7 to 40 characters) that resolves to a commit: that is the sha logged, and `✓ livré :` names it (« sha déclaré par le script ») — it wins over
+  HEAD, during a wave or not;
+- the file holds anything else (not a commit, several lines, `HEAD` or a branch name — a revision would be resolved after the script, possibly at another lot's commit, so only a sha is accepted): the delivery fails with a message that says so, nothing is logged;
+- the file is empty and the delivery runs **while a wave runs**: the log keeps `<sha>`, and if HEAD moved during the delivery a warning says
+  so (« la tête a avancé pendant la livraison ; sans sha déclaré par le script (CADENCE_DEPLOYED_FILE), le journal garde <sha> ») — the new
+  commit may be the script's, a running lot's, or a plan commit, and cadence cannot tell them apart;
+- the file is empty and **no wave runs**: the historical rule stays, a script that committed and pushed during the delivery has delivered the new
+  HEAD, which is logged (« head moved by the script »).
 
 cadence keeps what the script usually lacks: the preconditions (clean tree, pushed
 `HEAD`), the lock (never two deliveries at once), the delivery log and the lots
 delivered. Arguments are quoted for `sh`, so spaces and quotes reach the script
 intact. If the script commits and pushes during the delivery (stamping a
-changelog entry, say), the new `HEAD` is the sha recorded as delivered. Exit code
+changelog entry, say), outside a wave the new `HEAD` is the sha recorded as delivered; during a wave, or to be exact
+about it anywhere, the script declares it in `CADENCE_DEPLOYED_FILE` (above). Exit code
 0 of the script means delivered; `verify` checks, if any, run after it.
 
 ## verify: replay the effect checks, outside a delivery

package/docs/fonctionnement-wave-dark.svg

@@ -1,6 +1,6 @@
 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1320 350" width="1320" height="350" role="img" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif" font-size="13" fill="#e6edf3">
 <title>A lot inside an orchestrate wave</title>
-<desc>A lot without commits starts with a precheck (unless orchestrate.precheck is false), then by type through spec, mockup or sheet review and sealed acceptance tests, or straight to the implementation; then the code review, corrections (two passes, a third if the review converges), the UX pass if visible, once, after the compliant code review, and an automatic raf review.</desc>
+<desc>A lot without commits whose title cites a finding or an earlier lot starts with a precheck (unless orchestrate.precheck is false), then by type through spec, mockup or sheet review and sealed acceptance tests, or straight to the implementation; then the code review, corrections (two passes, a third if the review converges), the UX pass if visible, once, after the compliant code review, and an automatic raf review.</desc>
 <defs><marker id="arr2" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 z" fill="#8b949e"/></marker></defs>
 <rect width="1320" height="350" fill="#0d1117"/>
 <rect x="20" y="140" width="120" height="52" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5" stroke-dasharray="6 4"/>

package/docs/fonctionnement-wave-light.svg

@@ -1,6 +1,6 @@
 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1320 350" width="1320" height="350" role="img" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif" font-size="13" fill="#1f2328">
 <title>A lot inside an orchestrate wave</title>
-<desc>A lot without commits starts with a precheck (unless orchestrate.precheck is false), then by type through spec, mockup or sheet review and sealed acceptance tests, or straight to the implementation; then the code review, corrections (two passes, a third if the review converges), the UX pass if visible, once, after the compliant code review, and an automatic raf review.</desc>
+<desc>A lot without commits whose title cites a finding or an earlier lot starts with a precheck (unless orchestrate.precheck is false), then by type through spec, mockup or sheet review and sealed acceptance tests, or straight to the implementation; then the code review, corrections (two passes, a third if the review converges), the UX pass if visible, once, after the compliant code review, and an automatic raf review.</desc>
 <defs><marker id="arr2" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 z" fill="#57606a"/></marker></defs>
 <rect width="1320" height="350" fill="#ffffff"/>
 <rect x="20" y="140" width="120" height="52" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5" stroke-dasharray="6 4"/>