@sylad/cadence 1.9.0 → 1.11.0

package/dist/orchestrate/no-test.js

@@ -0,0 +1,41 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { readOrchestrateConfig } from '../config.js';
+/** Le script que `npm init` écrit quand on ne dit rien : il échoue toujours, ce n'est pas une suite. */
+const NPM_PLACEHOLDER = /no test specified/i;
+/** La commande de test que le dépôt laisse deviner : `scripts.test` de package.json, pytest de pyproject.toml, pom.xml ; null sinon. */
+export function probableTestCommand(repo) {
+    const pkg = join(repo, 'package.json');
+    if (existsSync(pkg)) {
+        try {
+            const test = JSON.parse(readFileSync(pkg, 'utf8')).scripts?.test;
+            if (typeof test === 'string' && test.trim() && !NPM_PLACEHOLDER.test(test))
+                return 'npm test';
+        }
+        catch {
+            // un package.json illisible ne donne aucune commande
+        }
+    }
+    const py = join(repo, 'pyproject.toml');
+    if (existsSync(py) && /pytest/i.test(readFileSync(py, 'utf8')))
+        return 'pytest';
+    if (existsSync(join(repo, 'pom.xml')))
+        return 'mvn test';
+    return null;
+}
+/** Le projet n'a pas de `orchestrate.test` : ce qu'on en dit, ou null quand il en a un. Un cadence.yaml illisible ne se signale pas ici (il a déjà sa propre erreur). */
+export function noTestGate(repo) {
+    let test;
+    try {
+        test = readOrchestrateConfig(join(repo, 'cadence.yaml')).test;
+    }
+    catch {
+        return null;
+    }
+    return test ? null : { probable: probableTestCommand(repo) };
+}
+/** La phrase du signalement, sans le nom du projet. */
+export function noTestText(g) {
+    const probable = g.probable ? ` · commande probable : ${g.probable} (à déclarer en orchestrate.test)` : '';
+    return `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)${probable}`;
+}

package/dist/orchestrate/registry.js

@@ -170,6 +170,16 @@ export function liveSlots(home) {
 const MAX_SLOT_INDEX = 64;
 /** Intervalle des rappels d'attente dans le journal. */
 const WAIT_REPORT_MS = 60_000;
+/** L'attente d'un créneau a été interrompue par `abandon` (L332) : aucun créneau n'a été pris, la session ne part pas. */
+export class SlotAbandoned extends Error {
+    reason;
+    /** Renseigné par `runSession` quand une session précédente de l'étape a déjà tourné : sa sortie et ses jetons ne se perdent pas. */
+    after;
+    constructor(reason) {
+        super(`attente de créneau abandonnée : ${reason}`);
+        this.reason = reason;
+    }
+}
 /**
  * Attend que le nombre de sessions vivantes, TOUTES vagues confondues et quel que soit l'index de leur créneau,
  * soit sous `cap` (le plafond de cette vague), puis prend le premier créneau libre (un pid mort est repris) et
@@ -180,6 +190,10 @@ const WAIT_REPORT_MS = 60_000;
  *
  * `onWait(holders, waitedMs)` : appelé quand on commence à attendre (0 ms), puis toutes les minutes.
  * `onGot(waitedMs)` : appelé à l'obtention, seulement si on a attendu.
+ * `abandon()` : relu seulement pendant une VRAIE attente, c'est-à-dire une fois qu'une première tentative n'a pas trouvé de créneau libre,
+ * puis à chaque tour ; une raison en retour interrompt l'attente par `SlotAbandoned`, sans prendre de créneau (L332 : `--drop` et
+ * `--stop-after-current` ne laissent pas un lot en attente). Un créneau libre est toujours pris, même si une demande est déjà posée :
+ * la relance d'une session coupée n'est pas une attente, la demande d'arrêt s'applique ensuite.
  */
 export async function acquireSlot(home, cap, opts) {
     mkdirSync(slotsDir(home), { recursive: true });
@@ -188,7 +202,14 @@ export async function acquireSlot(home, cap, opts) {
     let reportedAt = null;
     const pollMs = opts.pollMs ?? 2000;
     const live = opts.slots ?? liveSlots; // injectable : les tests simulent une vague qui prend un créneau entre les deux comptées
+    const checkAbandon = () => {
+        const why = opts.abandon?.();
+        if (why)
+            throw new SlotAbandoned(why);
+    };
     for (;;) {
+        if (reportedAt !== null)
+            checkAbandon(); // pas à la première tentative : un créneau libre est pris même si une demande est posée
         if (live(home).length < cap) {
             for (let k = 0; k < MAX_SLOT_INDEX; k++) {
                 const file = join(slotsDir(home), `slot-${k}.lock`);
@@ -204,6 +225,8 @@ export async function acquireSlot(home, cap, opts) {
                 break;
             }
         }
+        if (reportedAt === null)
+            checkAbandon(); // la première tentative a échoué : l'attente commence, la demande déjà posée l'interrompt sans attendre un tour
         if (reportedAt === null || now() - reportedAt >= (opts.reportMs ?? WAIT_REPORT_MS)) {
             reportedAt = now();
             opts.onWait?.(live(home), reportedAt - t0);

package/dist/orchestrate/snapshot.js

@@ -1,5 +1,5 @@
 import { spawn } from 'node:child_process';
-import { chmodSync, cpSync, existsSync, mkdirSync, readFileSync, realpathSync, symlinkSync } from 'node:fs';
+import { chmodSync, cpSync, existsSync, mkdirSync, readFileSync, readlinkSync, realpathSync, rmSync, symlinkSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { join, sep } from 'node:path';
 import { createInterface } from 'node:readline';
@@ -74,6 +74,34 @@ export function takeSnapshot(waveDir, packageRoot) {
     }
     return tool;
 }
+/**
+ * L330 : `<vague>/tool/node_modules` vise le `node_modules` de la copie qui a lancé la vague ; la purge de `npm run service`
+ * retire cette copie quand elle sort des versions gardées, et le lien reste pendu (la reprise planterait sur `yaml`).
+ * Si le lien ne se résout plus, on le refait vers le `node_modules` du paquet courant (la copie en service) et on le dit
+ * (message rendu) ; s'il est irréparable, `SnapshotRefusal` : un refus clair, pas une trace de pile. Rien à faire : undefined.
+ */
+export function repairSnapshotModules(waveDir, packageRoot) {
+    const link = join(toolDirOf(waveDir), 'node_modules');
+    if (existsSync(join(link, 'yaml', 'package.json')))
+        return undefined;
+    let was = 'absent';
+    try {
+        was = readlinkSync(link);
+    }
+    catch {
+        /* pas un lien (ou rien) : on le remplace quand même */
+    }
+    let modules;
+    try {
+        modules = resolveModulesDir(packageRoot);
+    }
+    catch (e) {
+        throw new SnapshotRefusal(`le node_modules de l'instantané de la vague (${was}) ne se résout plus et celui du paquet courant non plus, reprise impossible : ${e instanceof Error ? e.message : e}`);
+    }
+    rmSync(link, { recursive: true, force: true });
+    symlinkSync(modules, link, 'dir');
+    return `instantané : node_modules (${was}) ne se résolvait plus, la copie qui l'avait lancé a été retirée de la mise en service ; relié à ${modules}`;
+}
 export const snapshotExists = (waveDir) => existsSync(join(toolDirOf(waveDir), 'bin', 'cadence.js'));
 /**
  * La vague lit-elle `control.log` (`--drop`, `--stop-after-current`, L79) ? Elle tourne sur son instantané : une vague lancée

package/dist/orchestrate/state.js

@@ -4,6 +4,8 @@ import { tmpdir } from 'node:os';
 import { join, relative } from 'node:path';
 import { gitCommonDir, gitRoot } from '../git.js';
 /** Début de l'avertissement d'un rapport de précheck illisible (Sonnet) : le journal le garde, `cadence perf` s'en sert pour ne pas compter ce lot « non » (L293). */
+/** Avertissement d'un rapport du précheck local illisible : l'étape reste `ok`, le lot se replie sur Sonnet (L322, lu par `cadence perf` pour compter l'échec du local). */
+export const LOCAL_PRECHECK_UNREADABLE = 'contrôle préalable : rapport du modèle local illisible';
 export const PRECHECK_UNREADABLE = 'contrôle préalable illisible, implémentation lancée';
 export function newLot(o) {
     return { ...o, status: 'queued', pass: 0, next: null, steps: [], constats: [], verdict: null, uxVerdict: null, questions: [], choix: [], answers: [], proposals: [], warnings: [], outcome: null };
@@ -61,22 +63,25 @@ export class RunStore {
     static runsDir(launchDir) {
         return join(launchDir, '.cadence', 'runs');
     }
-    /** La dernière vague lancée (par date de lancement : un identifiant libre comme `ol-gains-1` ne se range pas par ordre alphabétique) ; avec `unfinished`, la dernière qui n'est pas terminée. */
-    static last(launchDir, opts = {}) {
+    /** Les vagues du dossier, la plus récente d'abord (par date de lancement : un identifiant libre comme `ol-gains-1` ne se range pas par ordre alphabétique). */
+    static all(launchDir) {
         const base = RunStore.runsDir(launchDir);
         if (!existsSync(base))
-            return null;
-        const stores = readdirSync(base)
+            return [];
+        return readdirSync(base)
             .filter((n) => existsSync(join(base, n, 'wave.json')))
             .map((id) => new RunStore(launchDir, id))
             .map((store) => ({ store, wave: store.readWave() }))
             // lancement le plus récent d'abord ; à date égale (ou illisible), l'identifiant le plus grand
             .sort((a, b) => (b.wave?.created ?? '').localeCompare(a.wave?.created ?? '') || b.store.id.localeCompare(a.store.id));
-        for (const { store, wave } of stores) {
-            if (!opts.unfinished || wave?.status !== 'done')
-                return store;
-        }
-        return null;
+    }
+    /** La dernière vague lancée. */
+    static last(launchDir) {
+        return RunStore.all(launchDir)[0]?.store ?? null;
+    }
+    /** Les vagues qui ne sont pas terminées (une vague illisible compte : elle n'est pas `done`), la plus récente d'abord (L309). */
+    static unfinished(launchDir) {
+        return RunStore.all(launchDir).filter((x) => x.wave?.status !== 'done').map((x) => x.store);
     }
     static find(launchDir, id) {
         return existsSync(join(RunStore.runsDir(launchDir), id, 'wave.json')) ? new RunStore(launchDir, id) : null;

package/dist/orchestrate/table.js

@@ -152,6 +152,18 @@ export function blockingLots(lots, repo, sha, ancestor = isAncestor, read = gitC
 }
 /** Tests déjà rouges au départ listés un par un dans le tableau ; au-delà, un compte. */
 const BASELINE_LISTED = 30;
+/**
+ * La commande de reprise d'une vague, SEULE forme que le programme imprime (L309) : `--resume --wave <id>` et non `--resume <id>`, car un id qui ressemble à un lot
+ * (`suite2`) est lu comme un lot à lancer sans `--wave` (et refusé), et `--resume` sans vague est refusé dès que le dossier en garde plusieurs non terminées.
+ * `extra` : les options qui suivent (`--drop a:L1`, `--integrate a:L1`...).
+ */
+export function resumeCommand(waveId, ...extra) {
+    return ['cadence orchestrate --resume --wave', waveId, ...extra].join(' ');
+}
+/** La commande qui répond à une question (L309) : la reprise ci-dessus, avec `--answer`. */
+export function resumeAnswerHint(waveId, l) {
+    return resumeCommand(waveId, '--answer', `${l.project}:${l.lot}`, '"…"');
+}
 /** Le tableau de fin de vague (ou de `--status`), une ligne par lot puis le total et les questions. */
 export function renderTable(wave, lots, deps = {}) {
     const rows = lots.map((l) => [`${l.project}:${l.lot}`, LABEL[l.status], String(l.pass), review(l), ux(l), String(commits(l)), k(counted(l)), `${minutes(l)} min`]);
@@ -163,7 +175,7 @@ export function renderTable(wave, lots, deps = {}) {
     const tail = [`${by('ready')} prêt(s)`, by('question') ? `${by('question')} question(s)` : '', by('handed-back') + by('failed') ? `${by('handed-back') + by('failed')} rendu(s) au lead` : '', by('suspended') ? `${by('suspended')} suspendu(s)` : ''].filter(Boolean);
     out.push(`vague ${wave.id} : ${k(wave.consumed)} / ${m(wave.budget)} comptés (lecture de cache ${m(wave.cacheRead)}) — ${tail.join(', ')} — ${wave.status}`);
     for (const l of lots.filter((x) => x.status === 'question')) {
-        out.push(`question : ${l.project}:${l.lot} — « ${l.questions.join(' / ')} » (cadence orchestrate --resume --answer ${l.project}:${l.lot} "…")`);
+        out.push(`question : ${l.project}:${l.lot} — « ${l.questions.join(' / ')} » (${resumeAnswerHint(wave.id, l)})`);
     }
     for (const l of lots.filter((x) => x.status === 'handed-back' || x.status === 'failed' || x.status === 'suspended')) {
         out.push(`${l.project}:${l.lot} — ${l.outcome ?? LABEL[l.status]}`);

package/dist/perf.js

@@ -157,6 +157,19 @@ function causeWindow(passes, w, cache) {
     const withFindings = classified + unclassified;
     return { top, classified, unclassified, withoutFindings, unclassifiedShare: withFindings === 0 ? null : unclassified / withFindings, byReview };
 }
+/** La sorte d'étape sous laquelle la hausse se compte : `review` et `review-small` ne font qu'une (la taille du lot choisit l'une ou l'autre, `orchestrate.review.threshold` : le passage de l'une à l'autre n'est pas une hausse). */
+const carrierKind = (kind) => (kind === 'review-small' ? 'review' : kind);
+/** L'étape qui porte la hausse (L312) : la sorte d'étape dont la moyenne des jetons par lot monte le plus ; null sans hausse nette du total par lot, ou sans lot dans l'une des fenêtres. */
+function carrierOf(current, previous) {
+    if (current.length === 0 || previous.length === 0)
+        return null;
+    const mean = (lots, kind) => lots.reduce((sum, l) => sum + (l.get(kind) ?? 0), 0) / lots.length;
+    const kinds = new Set([...current, ...previous].flatMap((l) => [...l.keys()]));
+    const rises = [...kinds].map((kind) => ({ kind, delta: mean(current, kind) - mean(previous, kind) }));
+    const net = rises.reduce((sum, r) => sum + r.delta, 0);
+    const top = rises.sort((a, b) => b.delta - a.delta || a.kind.localeCompare(b.kind))[0];
+    return net > 0 && top && top.delta > 0 ? top : null;
+}
 export function computePerf(input) {
     const { plans, cache, windows, today } = input;
     const hasPlans = plans.size > 0;
@@ -258,7 +271,10 @@ export function computePerf(input) {
                 continue;
             // Un lot passé par la chaîne spec (écran ou back) coûte plus que le lot ordinaire de même estimate (mesuré le 12–18-10 : +150 k à l'estimate 0,5, +30 k à 1 ; 450 k est l'écart de budget, pas l'écart mesuré) : classe à part, sinon l'arrivée de ces lots dans une fenêtre passe pour un lot ordinaire plus lourd (L240).
             const key = `${p.estimate}${d.j.steps.some((x) => SPEC_CHAIN.has(x.kind)) ? '+spec' : ''}`;
-            classes.set(key, [...(classes.get(key) ?? []), counted.reduce((sum, x) => sum + x.counted, 0)]);
+            const kinds = new Map();
+            for (const x of counted)
+                kinds.set(carrierKind(x.kind), (kinds.get(carrierKind(x.kind)) ?? 0) + x.counted);
+            classes.set(key, [...(classes.get(key) ?? []), { total: counted.reduce((sum, x) => sum + x.counted, 0), kinds }]);
         }
         return classes;
     };
@@ -266,8 +282,9 @@ export function computePerf(input) {
     const byEstimate = {};
     const classKeys = [...new Set([...byClass.current.keys(), ...byClass.previous.keys()])].sort(byEstimateKey);
     for (const key of classKeys) {
-        const vals = both(windows, (w) => median((w === windows.current ? byClass.current : byClass.previous).get(key) ?? []));
-        byEstimate[key] = mk(vals, { current: byClass.current.get(key)?.length ?? 0, previous: byClass.previous.get(key)?.length ?? 0 }, 'up', twinFirstTime);
+        const lotsOfClass = both(windows, (w) => (w === windows.current ? byClass.current : byClass.previous).get(key) ?? []);
+        const vals = both(windows, (w) => median((w === windows.current ? lotsOfClass.current : lotsOfClass.previous).map((l) => l.total)));
+        byEstimate[key] = { ...mk(vals, { current: lotsOfClass.current.length, previous: lotsOfClass.previous.length }, 'up', twinFirstTime), carrier: carrierOf(lotsOfClass.current.map((l) => l.kinds), lotsOfClass.previous.map((l) => l.kinds)) };
     }
     const reviewShare = both(windows, (w) => {
         let review = 0;
@@ -359,7 +376,7 @@ export function computePerf(input) {
     };
     const handed = mk(handedOut, lotsOf, 'up', twinEscaped, planNote);
     const interventions = { handedOut: { ...handed, count: handedCount }, ux: mk(ux, visibleCounts, 'up', twinEscaped), dedicatedUx: mk(dedicatedUx, visibleCounts, null, null) };
-    const precheck = { yes: mk(precheckYes, both(windows, (w) => prechecked(w).length), null, null) };
+    const precheck = { yes: mk(precheckYes, both(windows, (w) => prechecked(w).length), null, null), ...precheckMeasure(windows, rendered) };
     const tokens = { byEstimate, reviewShare: mk(reviewShare, both(windows, (w) => rendered(w).length), 'up', twinFirstTime) };
     const delays = {
         createdToDone: mk({ current: median(createdToDone.current), previous: median(createdToDone.previous) }, sizes(createdToDone), 'up', twinFirstTime, planNote),
@@ -402,11 +419,57 @@ export function computePerf(input) {
     const bottleneck = bottleneckOf(causes.current);
     for (const [key, ind] of indicatorLines(result))
         if (ind.warn)
-            result.warnings.push(`⚠ ${key.label} : ${describe(ind, key.kind)} → ${DECISIONS[key.decision]}`);
+            result.warnings.push(`⚠ ${key.label} : ${describe(ind, key.kind)} → ${decisionOf(key, ind, result)}`);
     if (bottleneck)
         result.warnings.push(bottleneck);
     return result;
 }
+const minutesOf = (s) => {
+    const from = Date.parse(s.started ?? '');
+    const to = Date.parse(s.ended ?? '');
+    return Number.isNaN(from) || Number.isNaN(to) || to < from ? 0 : (to - from) / 60_000;
+};
+/** Le contrôle préalable mesuré (L322) : répartition des verdicts, durée et tokens des sessions (local, Sonnet), gain des « oui », une ligne par lot de la fenêtre courante. */
+function precheckMeasure(windows, rendered) {
+    const verdicts = (w) => {
+        const out = { oui: 0, partiel: 0, non: 0 };
+        for (const d of rendered(w))
+            if (d.j.precheck)
+                out[d.j.precheck]++;
+        return out;
+    };
+    const cost = (w) => {
+        const set = rendered(w);
+        const steps = set.flatMap((d) => d.j.steps.filter((s) => s.kind === 'precheck'));
+        const local = steps.filter((s) => s.model === 'local');
+        const sonnet = steps.filter((s) => s.model !== 'local');
+        // Un échec du local = une étape qui n'a pas fini `ok`, ou finie `ok` mais au rapport illisible (docs/perf.md : « ended without a usable report »).
+        const unusable = new Set(set.filter((d) => d.j.localUnreadable).flatMap((d) => d.j.steps.filter((s) => s.kind === 'precheck' && s.model === 'local')));
+        const implement = set.flatMap((d) => d.j.steps.filter((s) => s.kind === 'implement' && s.counted !== undefined).map((s) => s.counted));
+        const avoided = set.filter((d) => d.j.precheck === 'oui' && d.j.status === 'handed-back').length;
+        const typical = median(implement);
+        return {
+            local: { runs: local.length, failed: local.filter((s) => s.status !== 'ok' || unusable.has(s)).length, minutes: local.reduce((n, s) => n + minutesOf(s), 0) },
+            sonnet: { runs: sonnet.length, minutes: sonnet.reduce((n, s) => n + minutesOf(s), 0), tokens: sonnet.reduce((n, s) => n + (s.counted ?? 0), 0) },
+            avoided: { sessions: avoided, tokens: avoided === 0 ? 0 : typical === null ? null : avoided * typical },
+        };
+    };
+    const lots = rendered(windows.current).flatMap((d) => {
+        const steps = d.j.steps.filter((s) => s.kind === 'precheck');
+        if (steps.length === 0 && !d.j.precheck)
+            return [];
+        const local = steps.find((s) => s.model === 'local');
+        const sonnet = steps.filter((s) => s.model !== 'local');
+        return [{
+                project: d.j.project,
+                lot: d.j.lot,
+                verdict: d.j.precheck ?? null,
+                local: local ? { status: local.status === 'ok' && d.j.localUnreadable ? 'illisible' : local.status, minutes: minutesOf(local) } : null,
+                sonnet: sonnet.length ? { minutes: sonnet.reduce((n, s) => n + minutesOf(s), 0), tokens: sonnet.reduce((n, s) => n + (s.counted ?? 0), 0) } : null,
+            }];
+    });
+    return { verdicts: both(windows, verdicts), cost: both(windows, cost), lots };
+}
 /** Goulot net (R19) : une cause pèse au moins la moitié des passes classées de la fenêtre courante, avec au moins dix passes classées. */
 function bottleneckOf(w) {
     const first = w.top[0];
@@ -475,6 +538,20 @@ const signed = (c) => `${c >= 0 ? '+' : '−'}${Math.round(100 * Math.abs(c))} %
 function describe(ind, kind) {
     return `${value(ind.current, kind)} (précédente ${value(ind.previous, kind)}${ind.change === null ? '' : `, ${signed(ind.change)}`})`;
 }
+/**
+ * La décision d'un ⚠ (L312). Celle des tokens par lot cite l'étape qui porte la hausse : quand la part conforme du premier coup monte en même temps,
+ * la hausse est de la qualité payée à cette étape, plus une estimate fausse ; sinon l'estimate reste suspecte, avec l'étape.
+ */
+function decisionOf(line, ind, r) {
+    const carrier = ind.carrier;
+    if (line.decision !== 'tokens' || !carrier)
+        return DECISIONS[line.decision];
+    const where = `la hausse est portée par l'étape ${carrier.kind} (+${value(carrier.delta, 'tokens')} par lot)`;
+    const { current, previous } = r.corrections.firstTime;
+    if (current !== null && previous !== null && current > previous)
+        return `${where} alors que la part conforme du premier coup monte : de la qualité payée, pas une estimate fausse ; juger cette étape (modèle, effort, passes) avant de recaler l'estimate`;
+    return `l'estimate est mal calibrée : ${where} : redécouper le lot ou recaler l'estimate et les budgets`;
+}
 /** Les lignes que désigne le chemin `twin` d'un indicateur. */
 function twinsByPath(lines) {
     const at = (label) => lines.find(([l]) => l.label === label);
@@ -496,7 +573,7 @@ export function perfHeader(r) {
         if (!ind.warn)
             continue;
         const twin = ind.twin ? byPath.get(ind.twin) : undefined;
-        header.push(`⚠ ${line.label} : ${describe(ind, line.kind)}${twin ? ` · ${twin[0].label} : ${describe(twin[1], twin[0].kind)}` : ''} → ${DECISIONS[line.decision]}`);
+        header.push(`⚠ ${line.label} : ${describe(ind, line.kind)}${twin ? ` · ${twin[0].label} : ${describe(twin[1], twin[0].kind)}` : ''} → ${decisionOf(line, ind, r)}`);
     }
     header.push(...r.warnings.filter((w) => w.startsWith('⚠ goulot')));
     return header;
@@ -541,7 +618,7 @@ export function renderPerf(r) {
         if (ind.note)
             parts.push(ind.note);
         if (ind.warn)
-            parts.push(`→ ${DECISIONS[line.decision]}`);
+            parts.push(`→ ${decisionOf(line, ind, r)}`);
         if (extra?.[1].warn)
             parts.push(`→ ${DECISIONS[extra[0].decision]}`);
         return parts.join(' · ');
@@ -564,6 +641,7 @@ export function renderPerf(r) {
     const h = r.interventions.handedOut.count;
     out.push(`  lots rendus puis terminés hors vague : ${h.current ?? 'n/d'} (précédente ${h.previous ?? 'n/d'})`);
     section('Contrôle préalable', ['part de « oui » du précheck']);
+    out.push(...precheckLines(r.precheck));
     out.push('', 'Tokens, délais et durées (médianes par lot ou par étape)');
     for (const l of lines.slice(LEGACY_LINES))
         out.push(row(l));
@@ -576,6 +654,30 @@ export function renderPerf(r) {
         out.push('', `${r.orphans} lot(s) de journal sans plan`);
     return out;
 }
+const plural = (n, one, many) => `${n} ${n > 1 ? many : one}`;
+/** Le contrôle préalable de la fenêtre courante (L322) : répartition, coût local puis Sonnet, gain des « oui », une ligne par lot. Rien sans session de contrôle ni verdict. */
+function precheckLines(p) {
+    const v = p.verdicts.current;
+    const c = p.cost.current;
+    if (v.oui + v.partiel + v.non + c.local.runs + c.sonnet.runs === 0)
+        return [];
+    const out = [`  précheck : oui ${v.oui} · partiel ${v.partiel} · non ${v.non}`];
+    if (c.local.runs > 0)
+        out.push(`  précheck local : ${plural(c.local.runs, 'session', 'sessions')}, ${plural(c.local.failed, 'échec', 'échecs')}, ${num(Math.round(c.local.minutes))} min`);
+    if (c.sonnet.runs > 0)
+        out.push(`  précheck Sonnet : ${plural(c.sonnet.runs, 'session', 'sessions')}, ${value(c.sonnet.tokens, 'tokens')} tokens, ${num(Math.round(c.sonnet.minutes))} min`);
+    if (c.avoided.sessions > 0)
+        out.push(`  gain des « oui » : ${plural(c.avoided.sessions, "session d'implémentation évitée", "sessions d'implémentation évitées")}${c.avoided.tokens === null ? ' (gain en tokens : n/d)' : ` (≈ ${value(c.avoided.tokens, 'tokens')} tokens)`}`);
+    for (const l of p.lots) {
+        const parts = [`${l.project}:${l.lot}`, l.verdict ?? 'sans verdict'];
+        if (l.local)
+            parts.push(`local ${l.local.status === 'ok' ? 'ok' : 'échec'} ${num(Math.round(l.local.minutes))} min`);
+        if (l.sonnet)
+            parts.push(`Sonnet ${num(Math.round(l.sonnet.minutes))} min, ${value(l.sonnet.tokens, 'tokens')} tokens`);
+        out.push(`    ${parts.join(' · ')}`);
+    }
+    return out;
+}
 /** Les plans des projets de `parent` (un niveau d'imbrication, R22) ; un plan illisible est sauté avec un avertissement (R16). */
 export function readPlans(parent, warn) {
     const plans = new Map();

package/dist/plan.js

@@ -72,6 +72,10 @@ export class Plan {
     get hasPublicField() {
         return !this.settings.format || !!this.settings.format.fields.public || this.read().lots.some((l) => l.public !== undefined);
     }
+    /** Un plan en lecture seule porte `visible` seulement si cadence.yaml le mappe (`plan.fields.visible`) ou si un lot l'écrit déjà sous ce nom. */
+    get hasVisibleField() {
+        return !this.settings.format || !!this.settings.format.fields.visible || this.read().lots.some((l) => l.visible);
+    }
     get readonly() {
         return !!this.settings.format;
     }
@@ -356,6 +360,18 @@ export class Plan {
         node.flow = true;
         this.lotNode(lotId).set('repos', node);
     }
+    /** Acquitte l'écart `docs.sync` d'un lot (L317) : clé `docs_ok: { date, reason }`, la raison est obligatoire. Jamais sur une sous-tâche. */
+    setDocsOk(ref, reason, today) {
+        this.writable();
+        if (ref.includes('/'))
+            throw new RafError(`docs-ok se pose sur un lot, pas sur une sous-tâche : ${ref}`);
+        const why = reason.trim();
+        if (!why)
+            throw new RafError('docs-ok exige une raison : raf docs-ok <lot> --reason "pourquoi la documentation reste telle quelle"');
+        const node = this.doc.createNode({ date: today, reason: why });
+        node.flow = true;
+        this.lotNode(ref).set('docs_ok', node);
+    }
     /** Remplace les ressources partagées d'un lot de tout statut (clé `uses:` en flow, avant `created:`) ; sans nom, retire la clé. Jamais sur une sous-tâche. */
     setUses(ref, names) {
         this.writable();
@@ -652,7 +668,7 @@ function foreignLots(raw, format) {
             into.problems.push(...lot.problems.map((p) => `${lot.id} : ${p}`));
         }
         else {
-            lots.push(lot);
+            lots.push(parent ? { ...lot, parent } : lot);
         }
     }
     return lots;
@@ -720,6 +736,8 @@ function normalizeLot(raw, problems = []) {
             problems.push(`spec : true ou false attendu (reçu « ${String(raw.spec)} »)`);
     }
     const gate = readGate(raw.gate, problems);
+    const okRaw = raw.docs_ok;
+    const docsOk = okRaw && typeof okRaw === 'object' && typeof okRaw.reason === 'string' && okRaw.reason.trim() !== '' ? { date: String(okRaw.date ?? ''), reason: okRaw.reason.trim() } : undefined;
     return {
         id: String(raw.id),
         title: String(raw.title ?? ''),
@@ -752,6 +770,7 @@ function normalizeLot(raw, problems = []) {
         ...(repoList(raw.repos).length ? { repos: repoList(raw.repos) } : {}),
         ...(asVerdict(raw.ux) ? { ux: asVerdict(raw.ux) } : {}),
         ...(asVerdict(raw.review) ? { review: asVerdict(raw.review) } : {}),
+        ...(docsOk ? { docsOk } : {}),
         problems,
     };
 }

package/dist/proc.js

@@ -12,6 +12,12 @@ let dying = false;
  * ses `trap` et le nettoyage de git (index.lock) ont ce temps pour finir avant le kill.
  */
 export const SIGNAL_GRACE_MS = 2_000;
+/**
+ * Attente, après la sortie de la commande racine, d'un signal de terminaison encore en route vers cadence tant que des
+ * processus suivis vivent ou que la racine est morte d'un tel signal : le terminal l'envoie au groupe entier, la racine
+ * peut être traitée la première.
+ */
+export const SIGNAL_PENDING_MS = 2_000;
 async function onSignal(sig) {
     if (dying)
         return; // un second signal pendant le nettoyage n'interrompt rien

package/dist/ref/add.js

@@ -1,5 +1,5 @@
 import { createHash } from 'node:crypto';
-import { existsSync, readFileSync, statSync } from 'node:fs';
+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';
@@ -42,7 +42,10 @@ export function parseSections(text, pages) {
 }
 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. */
+/**
+ * `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);
@@ -68,17 +71,25 @@ export function add(o) {
     const visees = new Set([...wanted, ...keep]);
     const rendered = new Set([...visees, ...citedPages(index, visees)]);
     const ordered = [...rendered].sort((a, b) => a - b);
-    renderPages(tools, file, ordered, join(docDir, 'pages'));
-    renderThumbnails(tools, file, total, join(docDir, 'thumbs'));
-    const images = [];
-    const placed = [];
+    // 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))
-            continue;
-        extractImages(tools, file, n, join(docDir, 'images'));
-        regions.set(n, imageRegions(tools, file, n));
+    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 };
@@ -113,4 +124,6 @@ export function add(o) {
     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 };
 }