@sylad/cadence 0.11.0 → 0.12.0

package/dist/orchestrate/launch.js

@@ -1,22 +1,58 @@
 import { spawn } from 'node:child_process';
-import { existsSync, readdirSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { delimiter, join, resolve } from 'node:path';
 import { parse } from 'yaml';
 import { RafError } from '../plan.js';
 import { isQuotaMessage, lacksStructuredOutput, parseSession, salvageUsage, sumTokens, tokensOf } from './result.js';
+/**
+ * Serveurs MCP d'une étape : Playwright pour `ux` et, sur un lot `visible`, pour `implement` et `fix` (fix-minors compris) ;
+ * et `review-small` d'un petit lot visible (sa seule revue d'ergonomie) ; rien pour `review`, ni pour un lot sans écran.
+ * Sorties dans `outputDir`, hors du dépôt.
+ */
+export function mcpServersFor(kind, visible, outputDir, small = false) {
+    if (!(kind === 'ux' || (visible && (kind === 'implement' || kind === 'fix' || (kind === 'review-small' && small)))))
+        return {};
+    return { playwright: { command: 'npx', args: ['-y', '@playwright/mcp@latest', '--output-dir', outputDir] } };
+}
+/** Dossier de sortie du Playwright MCP d'un lot : `<lotDir>/playwright`, chemin absolu. */
+export function playwrightDir(lotDir) {
+    return join(resolve(lotDir), 'playwright');
+}
+/** Écrit `<lotDir>/mcp-<étape>.json` (et, si Playwright est chargé, le dossier `playwright/`) ; rend le chemin absolu du fichier. */
+export function writeMcpConfig(lotDir, kind, visible, small = false) {
+    const dir = resolve(lotDir);
+    const out = playwrightDir(dir);
+    const servers = mcpServersFor(kind, visible, out, small);
+    if (servers.playwright)
+        mkdirSync(out, { recursive: true });
+    const file = join(dir, `mcp-${kind}.json`);
+    writeFileSync(file, `${JSON.stringify({ mcpServers: servers }, null, 2)}\n`);
+    return file;
+}
 /** Outils interdits à toute session : pas de sous-agent, pas de push, de livraison ni de verdict. */
 export const DISALLOWED = ['Agent', 'Bash(git push:*)', 'Bash(cadence deliver:*)', 'Bash(raf done:*)', 'Bash(raf review:*)', 'Bash(raf ux:*)'];
+/** Outils MCP du serveur Playwright, par le préfixe du serveur (sonde réelle du 07-10 : `mcp__playwright` expose tous les `browser_*`). */
+export const PLAYWRIGHT_TOOLS = 'mcp__playwright';
+/** Agents passés à `--agents` : l'agent d'une étape qui charge Playwright, s'il a une liste d'outils, y gagne les outils du serveur (sinon il ne peut pas l'appeler). */
+function agentsFor(spec, agents) {
+    const a = spec.agent ? agents[spec.agent] : undefined;
+    if (!spec.playwright || !spec.agent || !a?.tools)
+        return agents;
+    return { ...agents, [spec.agent]: { ...a, tools: [...a.tools, PLAYWRIGHT_TOOLS] } };
+}
 export function buildArgs(spec, agents) {
     const args = ['-p', spec.brief, '--output-format', 'json', '--json-schema', JSON.stringify(spec.schema), '--model', spec.model];
     if (spec.agent) {
         if (!agents[spec.agent])
             throw new RafError(`agent introuvable dans le paquet : ${spec.agent}`);
-        args.push('--agents', JSON.stringify(agents), '--agent', spec.agent);
+        args.push('--agents', JSON.stringify(agentsFor(spec, agents)), '--agent', spec.agent);
     }
     args.push('--session-id', spec.sessionId, '--permission-mode', spec.permissionMode);
     for (const d of spec.addDirs)
         args.push('--add-dir', d);
     args.push('--disallowedTools', ...DISALLOWED);
+    if (spec.mcpConfig)
+        args.push('--strict-mcp-config', '--mcp-config', spec.mcpConfig);
     return args;
 }
 /** Définitions d'agents du paquet (`agents/*.md`) au format de --agents. */
@@ -49,12 +85,14 @@ export function buildRetryArgs(spec, sessionId, agents) {
     if (spec.agent) {
         if (!agents[spec.agent])
             throw new RafError(`agent introuvable dans le paquet : ${spec.agent}`);
-        args.push('--agents', JSON.stringify(agents), '--agent', spec.agent);
+        args.push('--agents', JSON.stringify(agentsFor(spec, agents)), '--agent', spec.agent);
     }
     args.push('--resume', sessionId, '--permission-mode', spec.permissionMode);
     for (const d of spec.addDirs)
         args.push('--add-dir', d);
     args.push('--disallowedTools', ...DISALLOWED);
+    if (spec.mcpConfig)
+        args.push('--strict-mcp-config', '--mcp-config', spec.mcpConfig);
     return args;
 }
 /**
@@ -64,7 +102,7 @@ export function buildRetryArgs(spec, sessionId, agents) {
  * s'ajoutent à ceux de la session ; toujours rien après elle, c'est l'échec habituel.
  */
 export async function runSession(spec, deps) {
-    const launch = (args) => deps.claude(args, { cwd: spec.cwd, env: { CADENCE_ORCHESTRATED: spec.wave }, timeoutMs: spec.timeoutMs, onSpawn: deps.onSpawn });
+    const launch = (args) => deps.claude(args, { cwd: spec.cwd, env: { CADENCE_ORCHESTRATED: spec.wave, ...(spec.nodeBin || spec.toolBin ? { PATH: [spec.toolBin, spec.nodeBin, process.env.PATH ?? ''].filter(Boolean).join(delimiter) } : {}) }, timeoutMs: spec.timeoutMs, onSpawn: deps.onSpawn });
     const out = await launch(buildArgs(spec, deps.agents));
     const first = classify(out);
     const missing = first.kind === 'failed' && !out.timedOut && out.code === 0 ? lacksStructuredOutput(out.stdout) : null;

package/dist/orchestrate/node-env.js

@@ -0,0 +1,77 @@
+import { accessSync, constants, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, symlinkSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+export const realNodeFs = {
+    read: (f) => (existsSync(f) ? readFileSync(f, 'utf8') : null),
+    list: (d) => (existsSync(d) ? readdirSync(d) : []),
+    executable: (f) => {
+        try {
+            accessSync(f, constants.X_OK);
+            return statSync(f).isFile();
+        }
+        catch {
+            return false;
+        }
+    },
+};
+/** Dossier des versions de nvm : `$NVM_DIR/versions/node`, par défaut `~/.nvm/versions/node`. */
+export function nvmVersionsDir(env, home = homedir()) {
+    return join(env.NVM_DIR || join(home, '.nvm'), 'versions', 'node');
+}
+const parts = (v) => v.split('.').map(Number);
+const cmp = (a, b) => {
+    const x = parts(a);
+    const y = parts(b);
+    for (let i = 0; i < 3; i++)
+        if ((x[i] ?? 0) !== (y[i] ?? 0))
+            return (x[i] ?? 0) - (y[i] ?? 0);
+    return 0;
+};
+/**
+ * Node demandé par le `.nvmrc` à la racine d'un projet, résolu dans les versions installées de nvm : la plus haute
+ * dont le numéro commence par celui du fichier (`22`, `v22`, `22.22`, `v22.22.3`) et qui a un node exécutable. Pas de .nvmrc : rien à changer.
+ * .nvmrc illisible pour nous (`lts/*`, alias) ou version absente : refus nommant ce qui est demandé et où on a cherché
+ * — jamais de repli silencieux sur le node par défaut.
+ */
+export function resolveNode(repo, versionsDir, fs = realNodeFs) {
+    const raw = fs.read(join(repo, '.nvmrc'));
+    if (raw === null)
+        return { kind: 'none' };
+    const wanted = raw.trim();
+    const m = /^v?(\d+(?:\.\d+){0,2})$/.exec(wanted);
+    if (!m)
+        return { kind: 'missing', message: `.nvmrc « ${wanted} » : version non résoluble (seuls 22, v22, 22.22, v22.22.3 sont compris)` };
+    const want = m[1];
+    const matching = fs
+        .list(versionsDir)
+        .map((n) => /^v(\d+\.\d+\.\d+)$/.exec(n)?.[1])
+        .filter((v) => !!v && (v === want || v.startsWith(`${want}.`)))
+        .sort(cmp);
+    if (matching.length === 0)
+        return { kind: 'missing', message: `.nvmrc ${wanted} : aucun Node installé correspondant dans ${versionsDir}` };
+    // Une version dont le bin n'a pas de node exécutable (install vide ou cassée) donnerait un dossier de liens vide,
+    // donc un repli silencieux sur le node par défaut : on l'écarte, et une plus basse valide peut être retenue.
+    const found = matching.filter((v) => fs.executable(join(versionsDir, `v${v}`, 'bin', 'node')));
+    if (found.length === 0) {
+        const names = matching.map((v) => `v${v}`).join(', ');
+        return { kind: 'missing', message: `.nvmrc ${wanted} : ${names} trouvée(s) dans ${versionsDir} mais sans node exécutable dans bin (installation vide ou cassée)` };
+    }
+    const best = found[found.length - 1];
+    const skipped = matching.filter((v) => cmp(v, best) > 0).reverse().map((v) => `v${v}`);
+    return { kind: 'ok', version: `v${best}`, wanted, bin: join(versionsDir, `v${best}`, 'bin'), ...(skipped.length ? { skipped } : {}) };
+}
+/** Les seuls binaires d'une version de Node que les sessions voient : le reste de son bin (raf, cadence, claude… installés en global) ne doit pas masquer ceux du PATH. */
+export const NODE_LINKED = ['node', 'npm', 'npx', 'corepack'];
+/**
+ * Dossier de liens `<runDir>/node-bin/<version>/` : un lien vers chacun des `NODE_LINKED` présents dans `bin`. Recréé à
+ * chaque appel (départ et reprise), donc idempotent. C'est lui, et non `bin`, qui passe en tête du PATH des sessions.
+ */
+export function linkNodeBin(runDir, version, bin) {
+    const dir = join(runDir, 'node-bin', version);
+    rmSync(dir, { recursive: true, force: true });
+    mkdirSync(dir, { recursive: true });
+    for (const name of NODE_LINKED)
+        if (existsSync(join(bin, name)))
+            symlinkSync(join(bin, name), join(dir, name));
+    return dir;
+}

package/dist/orchestrate/registry.js

@@ -90,7 +90,8 @@ const WAIT_REPORT_MS = 60_000;
  */
 export async function acquireSlot(home, cap, opts) {
     mkdirSync(slotsDir(home), { recursive: true });
-    const t0 = Date.now();
+    const now = opts.now ?? Date.now; // injectable : les tests pilotent l'horloge
+    const t0 = now();
     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
@@ -103,15 +104,15 @@ export async function acquireSlot(home, cap, opts) {
                     continue;
                 if (live(home).length <= cap) {
                     if (reportedAt !== null)
-                        opts.onGot?.(Date.now() - t0);
+                        opts.onGot?.(now() - t0);
                     return () => releaseLock(file, process.pid);
                 }
                 releaseLock(file, process.pid); // pris à plusieurs en même temps : on rend, on retente
                 break;
             }
         }
-        if (reportedAt === null || Date.now() - reportedAt >= (opts.reportMs ?? WAIT_REPORT_MS)) {
-            reportedAt = Date.now();
+        if (reportedAt === null || now() - reportedAt >= (opts.reportMs ?? WAIT_REPORT_MS)) {
+            reportedAt = now();
             opts.onWait?.(live(home), reportedAt - t0);
         }
         await new Promise((r) => setTimeout(r, pollMs + Math.random() * pollMs * 0.25));

package/dist/orchestrate/schemas.js

@@ -30,7 +30,13 @@ export const REVIEW_SCHEMA = {
     },
     required: ['bloquants', 'majeurs', 'mineurs', 'constats', 'sousTaches', 'nonVerifie', 'verdict'],
 };
-export const schemaFor = (kind) => (kind === 'implement' || kind === 'fix' ? WORK_SCHEMA : REVIEW_SCHEMA);
+/** Sortie du contrôle préalable : `dejaPresent` vaut « oui » (rien à faire), « partiel » ou « non ». */
+export const PRECHECK_SCHEMA = {
+    type: 'object',
+    properties: { dejaPresent: { type: 'string', enum: ['oui', 'partiel', 'non'] }, preuves: strings, resume: str },
+    required: ['dejaPresent', 'preuves', 'resume'],
+};
+export const schemaFor = (kind) => (kind === 'precheck' ? PRECHECK_SCHEMA : kind === 'implement' || kind === 'fix' ? WORK_SCHEMA : REVIEW_SCHEMA);
 /** Contrôle la forme d'une sortie structurée : un champ absent ou mal typé est une erreur nommée. */
 export function checkShape(value, schema) {
     if (!value || typeof value !== 'object' || Array.isArray(value))

package/dist/orchestrate/snapshot.js

@@ -0,0 +1,99 @@
+import { spawn } from 'node:child_process';
+import { chmodSync, cpSync, existsSync, mkdirSync, realpathSync, symlinkSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join, sep } from 'node:path';
+import { createInterface } from 'node:readline';
+import { fileURLToPath } from 'node:url';
+/** Racine du paquet en cours d'exécution (dist/orchestrate/ ou src/orchestrate/ → deux niveaux au-dessus). */
+export const PACKAGE_ROOT = fileURLToPath(new URL('../..', import.meta.url));
+/** Posée par le processus relancé depuis la copie : il tourne déjà sur l'instantané, il n'en refait pas. */
+export const SNAPSHOT_ENV = 'CADENCE_SNAPSHOT';
+/** Vague déjà réservée (et copiée) par le processus d'origine : le processus relancé la reprend telle quelle. */
+export const RESERVED_ENV = 'CADENCE_WAVE_RESERVED';
+/** Environnement sans les variables de relance : le fils les lit, il ne les transmet ni aux sessions ni aux commandes du projet. */
+export function withoutLaunchVars(env) {
+    const { [SNAPSHOT_ENV]: _s, [RESERVED_ENV]: _r, ...rest } = env;
+    return rest;
+}
+const real = (p) => {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+};
+/** Vrai fils : CADENCE_SNAPSHOT désigne CE paquet (la copie qui s'exécute). Une valeur héritée d'une autre vague ne compte pas. */
+export const isSnapshotChild = (env, root = PACKAGE_ROOT) => !!env[SNAPSHOT_ENV] && real(env[SNAPSHOT_ENV]) === real(root);
+/** Entrées de `package.json#bin` : nom de commande → fichier de `bin/`. */
+const BIN_ENTRIES = { raf: 'raf.js', cadence: 'cadence.js' };
+/** Ce du paquet qui sert à l'exécution d'une vague ; node_modules est lié, jamais copié. */
+const COPIED = ['bin', 'dist', 'templates', 'agents', 'skills', 'package.json'];
+export const toolDirOf = (waveDir) => join(waveDir, 'tool');
+/** `<vague>/tool/bin` si la vague a un instantané (entrées `raf` et `cadence`), sinon rien : le PATH de la session ne change pas. */
+export const toolBinOf = (waveDir) => (existsSync(join(toolDirOf(waveDir), 'bin', 'raf')) ? join(toolDirOf(waveDir), 'bin') : undefined);
+/** Refus de prendre l'instantané (avant toute copie) : le message dit quoi faire. */
+export class SnapshotRefusal extends Error {
+}
+/**
+ * Le `node_modules` où les dépendances du paquet se résolvent réellement : celui du paquet, ou — installation npx ou
+ * locale — un dossier parent. On résout `yaml` depuis le paquet et on remonte jusqu'à son `node_modules`.
+ */
+export function resolveModulesDir(packageRoot) {
+    let file;
+    try {
+        file = createRequire(join(packageRoot, 'package.json')).resolve('yaml');
+    }
+    catch {
+        throw new SnapshotRefusal(`dépendances introuvables : « yaml » ne se résout pas depuis ${packageRoot} (installation incomplète ?) — instantané impossible, aucune vague lancée`);
+    }
+    const marker = `${sep}node_modules${sep}`;
+    const at = file.lastIndexOf(marker);
+    if (at < 0)
+        throw new SnapshotRefusal(`dépendances introuvables : « yaml » résolu hors de tout node_modules (${file}) — instantané impossible, aucune vague lancée`);
+    return file.slice(0, at + marker.length - 1);
+}
+/** Instantané du paquet dans `<vague>/tool/` : le code, les gabarits et les agents d'une vague ne bougent plus. */
+export function takeSnapshot(waveDir, packageRoot) {
+    const modules = resolveModulesDir(packageRoot); // avant toute copie
+    const tool = toolDirOf(waveDir);
+    mkdirSync(tool, { recursive: true });
+    for (const name of COPIED) {
+        const from = join(packageRoot, name);
+        if (existsSync(from))
+            cpSync(from, join(tool, name), { recursive: true });
+    }
+    symlinkSync(modules, join(tool, 'node_modules'), 'dir');
+    // Comme npm à l'installation : `raf` et `cadence` sont les bin/*.js de la copie (shebang `env node` conservé).
+    for (const [name, target] of Object.entries(BIN_ENTRIES)) {
+        const js = join(tool, 'bin', target);
+        if (!existsSync(js))
+            continue;
+        chmodSync(js, 0o755);
+        symlinkSync(target, join(tool, 'bin', name));
+    }
+    return tool;
+}
+export const snapshotExists = (waveDir) => existsSync(join(toolDirOf(waveDir), 'bin', 'cadence.js'));
+/** Relance réelle : un processus node sur la copie, signaux transmis, code de sortie rendu. */
+export function spawnReexec(toolDir, argv, env, sink) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, [join(toolDir, 'bin', 'cadence.js'), 'orchestrate', ...argv], { cwd: sink.cwd, env: { ...env, [SNAPSHOT_ENV]: toolDir }, stdio: ['inherit', 'pipe', 'pipe'] });
+        const lines = [createInterface({ input: child.stdout }).on('line', sink.out), createInterface({ input: child.stderr }).on('line', sink.err)];
+        const drained = Promise.all(lines.map((l) => new Promise((r) => l.once('close', r))));
+        const relay = (sig) => () => child.kill(sig);
+        const handlers = ['SIGINT', 'SIGTERM', 'SIGHUP'].map((s) => [s, relay(s)]);
+        for (const [s, h] of handlers)
+            process.on(s, h);
+        child.once('error', reject);
+        child.once('close', async (code, signal) => {
+            for (const [s, h] of handlers)
+                process.off(s, h);
+            await drained;
+            // Le fils est mort d'un signal (il se nettoie puis se le renvoie) : on meurt du même, comme sans instantané.
+            if (signal)
+                process.kill(process.pid, signal);
+            resolve(code ?? 1);
+        });
+    });
+}

package/dist/orchestrate/table.js

@@ -18,7 +18,15 @@ function review(l) {
     const fixes = l.pass === 0 ? '' : ` après ${l.pass} correction${l.pass > 1 ? 's' : ''}`;
     if (l.status === 'ready')
         return `conforme${fixes}`;
-    return `non conforme (${l.code.bloquants} bloquant, ${l.code.majeurs} majeur)`;
+    const verdict = l.code.conforme ? 'conforme' : `non conforme (${l.code.bloquants} bloquant, ${l.code.majeurs} majeur)`;
+    // Rendu, échoué ou suspendu pour une autre cause que la revue (dépôt sale, session coupée…) : la colonne ne présente pas
+    // un verdict de revue comme la cause ; elle donne le dernier verdict réel, la cause est dans les lignes sous le tableau.
+    const stopped = l.status === 'handed-back' || l.status === 'failed' || l.status === 'suspended' || l.status === 'question';
+    const last = l.steps[l.steps.length - 1];
+    const byReview = !l.code.conforme && !!last && last.status === 'ok' && (last.kind === 'review' || last.kind === 'review-small');
+    if (stopped && !byReview)
+        return `${verdict} (dernier verdict ; rendu pour une autre cause)`;
+    return verdict;
 }
 function ux(l) {
     if (!l.visible)
@@ -51,6 +59,8 @@ export function renderTable(wave, lots) {
     for (const l of lots) {
         if (l.uxNote)
             out.push(`${l.project}:${l.lot} — ${l.uxNote}`);
+        if (l.uxCaptures)
+            out.push(`${l.project}:${l.lot} — captures Playwright : ${l.uxCaptures}`);
         for (const w of l.warnings)
             out.push(`${l.project}:${l.lot} — ⚠ ${w}`);
         for (const x of l.choix ?? [])

package/dist/plan.js

@@ -122,6 +122,35 @@ export class Plan {
         }
         return { patterns, invalid };
     }
+    /** Commits acquittés (`raf ignore`) : exemptés de « sans lot » et d'« inconnu », par sha complet ou par sujet exact. */
+    get acknowledged() {
+        const raw = this.doc.get('acknowledged');
+        if (!isSeq(raw))
+            return [];
+        return raw.toJSON().flatMap((e) => {
+            const o = (e ?? {});
+            const sha = o.sha == null ? undefined : String(o.sha);
+            const subject = o.subject == null ? undefined : String(o.subject);
+            if (!sha && !subject)
+                return [];
+            return [{ sha, subject, date: String(o.date ?? ''), reason: o.reason == null ? undefined : String(o.reason) }];
+        });
+    }
+    /** Acquitte un commit : une ligne datée dans la section `acknowledged:` du plan. */
+    acknowledge(entry) {
+        this.writable();
+        // Déjà acquitté (même sha, ou même sujet pour une entrée par sujet) : on garde la première ligne et son motif.
+        if (this.acknowledged.some((a) => (entry.sha ? a.sha === entry.sha : a.sha === undefined && a.subject === entry.subject)))
+            return;
+        let list = this.doc.get('acknowledged');
+        if (!isSeq(list)) {
+            list = this.doc.createNode([]);
+            this.doc.set('acknowledged', list);
+        }
+        const node = this.doc.createNode(Object.fromEntries(Object.entries(entry).filter(([, v]) => v !== undefined)));
+        node.flow = true;
+        list.add(node);
+    }
     /** Fichier de configuration lu pour ce plan, null quand on n'en connaît pas (cadence.yaml à la racine alors). */
     get configFile() {
         return this.settings.config ?? null;

package/dist/session.js

@@ -108,7 +108,7 @@ export function sessionStart(ctx, opts) {
         done.push(`${recent.orphans.length} commit(s) sans lot`);
     section(out, `Fait depuis ${opts.since}`, done);
     section(out, 'Récurrent', recurringByDue(lots, today).map((l) => `${l.id}  ${l.title} — ${dueLine(l, today)}`));
-    section(out, 'Écarts (raf check)', audit(plan, ctx.root, ctx.newsDir, today).map((i) => `✗ ${i.message}`));
+    section(out, 'Écarts (raf check)', audit(plan, ctx.root, ctx.newsDir, today).map((i) => `${i.warning ? '⚠' : '✗'} ${i.message}`));
     section(out, 'Dépôt', [repoLine(ctx.root).line]);
     section(out, 'Effets en production (cadence verify)', ctx.effects ?? []);
     section(out, 'Faits propres au projet', projectFacts(ctx, opts.since));
@@ -131,7 +131,7 @@ export function sessionClose(ctx, opts) {
     const quiet = plan.lots().filter((l) => l.status === 'doing' && !isRecurring(l) && !recent.byLot.has(l.id));
     section(out, 'Lots en cours', quiet.map((l) => `${l.id}  ${l.title} — aucun commit sur la période : ${plan.readonly ? "le fermer ou l'annoter avec l'outil du projet" : 'raf done ou raf note'}`));
     const issues = audit(plan, ctx.root, ctx.newsDir, today);
-    section(out, 'Écarts (raf check)', issues.map((i) => `✗ ${i.message}`));
+    section(out, 'Écarts (raf check)', issues.map((i) => `${i.warning ? '⚠' : '✗'} ${i.message}`));
     const repo = repoLine(ctx.root);
     const lock = lockStatus(ctx.shared);
     section(out, 'Dépôt', [repo.line, ...(lock ? [lock.line] : [])]);
@@ -149,7 +149,10 @@ export function sessionClose(ctx, opts) {
             section(out, "Nettoyage : parcours interrompu, rien n'est proposé", [e instanceof Error ? e.message : String(e)]);
         }
     }
-    const open = issues.length + repo.open + (lock?.live ? 1 : 0);
+    else {
+        out(`\n(aucun motif de nettoyage déclaré — exemple de session.clean, dans cadence.yaml : session: { clean: [ "tmp/*", "~/partage/capture-*.png" ], cleanDays: 7 } ; chemins relatifs à la racine ou absolus, cleanDays = âge minimal en jours)`);
+    }
+    const open = issues.filter((i) => !i.warning).length + repo.open + (lock?.live ? 1 : 0);
     out(open === 0 ? '\n✓ prêt à fermer' : `\n✗ pas fermé : ${open} point(s)`);
     return open === 0 ? 0 : 1;
 }

package/dist/state.js

@@ -61,38 +61,43 @@ export function readLock(dir) {
 export function lockAlive(lock) {
     return lock.unreadable ? lock.ageMs < 5_000 : pidAlive(lock.pid);
 }
-/** Pose le verrou de façon atomique (lien vers un fichier complet) ; false s'il existe déjà. */
-export function writeLock(dir, lock) {
-    const tmp = join(dir, `deliver.lock.${lock.pid}.${Date.now()}.tmp`);
-    writeFileSync(tmp, JSON.stringify(lock));
+/** Pose un fichier de façon atomique (lien vers un fichier complet : il n'existe jamais à moitié écrit) ; false s'il existe déjà (EEXIST) ; toute autre erreur est relancée. `tag` distingue les fichiers temporaires d'un même processus. */
+export function linkNewFile(file, content, tag) {
+    const tmp = `${file}.${tag}.${Date.now()}.tmp`;
+    writeFileSync(tmp, content);
     try {
-        linkSync(tmp, lockPath(dir));
+        linkSync(tmp, file);
         return true;
     }
-    catch {
-        return false;
+    catch (e) {
+        // Seul EEXIST veut dire « déjà là » ; EPERM, EMLINK… (pas de liens physiques ici) remontent au lieu de passer pour un verrou tenu.
+        if (e.code === 'EEXIST')
+            return false;
+        throw e;
     }
     finally {
         rmSync(tmp, { force: true });
     }
 }
-/** Retire un verrou périmé seulement s'il est encore celui qu'on a lu ; sinon le laisse en place. */
-export function removeStaleLock(dir, seen) {
-    const aside = join(dir, `deliver.lock.stale.${process.pid}`);
+/**
+ * Retire un verrou périmé seulement s'il est encore celui qu'on a lu : il est écarté par renommage, `same` relit
+ * l'écart, et s'il a changé il est rendu à son nouveau porteur. Partagé par le verrou de livraison et celui de l'URL UX.
+ */
+export function removeStaleFile(file, same) {
+    const aside = `${file}.stale.${process.pid}`;
     try {
-        renameSync(lockPath(dir), aside);
+        renameSync(file, aside);
     }
     catch {
         return false;
     }
-    const now = readLockFile(aside);
-    if (now && now.pid === seen.pid && now.sha === seen.sha && now.started === seen.started) {
+    if (same(aside)) {
         rmSync(aside, { force: true });
         return true;
     }
     // Un autre processus a pris le verrou entre-temps : le lui rendre.
     try {
-        linkSync(aside, lockPath(dir));
+        linkSync(aside, file);
     }
     catch {
         // Un troisième l'a déjà repris : le sien fait foi.
@@ -100,6 +105,21 @@ export function removeStaleLock(dir, seen) {
     rmSync(aside, { force: true });
     return false;
 }
+/** Cause d'une pose de verrou impossible, en une ligne : « verrou <chemin> : <errno> » (le code, sinon le message). */
+export function lockFault(file, e) {
+    return `verrou ${file} : ${e?.code ?? (e instanceof Error ? e.message : String(e))}`;
+}
+/** Pose le verrou de façon atomique (lien vers un fichier complet) ; false s'il existe déjà. */
+export function writeLock(dir, lock) {
+    return linkNewFile(lockPath(dir), JSON.stringify(lock), lock.pid);
+}
+/** Retire un verrou périmé seulement s'il est encore celui qu'on a lu ; sinon le laisse en place. */
+export function removeStaleLock(dir, seen) {
+    return removeStaleFile(lockPath(dir), (aside) => {
+        const now = readLockFile(aside);
+        return !!now && now.pid === seen.pid && now.sha === seen.sha && now.started === seen.started;
+    });
+}
 /** Retire le verrou s'il appartient à ce processus. */
 export function releaseLock(dir, pid) {
     const lock = readLock(dir);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sylad/cadence",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "A small, repo-native working method: a versioned plan linked to your commits, a changelog with screenshots, session rituals and deliveries proven by their effect.",
   "license": "MIT",
   "author": "Sylvain Ladoire",

package/skills/lead/SKILL.md

@@ -14,7 +14,13 @@ commands (its CLAUDE.md names them), never with `raf start|done|note|ux|review`.
 
 ## Limits that always apply
 
-- **At most two subagents running at once.** Queue the rest.
+- **At most two subagents running at once.** Queue the rest. The sessions of an orchestrated wave
+  (section 2b) count toward this limit: orchestrate sessions plus subagents never exceed two. A wave
+  already caps itself (`--max-sessions`, 2 by default, shared by every wave); before starting a
+  subagent, check `cadence orchestrate --status`, and while a wave runs, start none beyond the free
+  slots. Count the free slots from what `--status` shows per wave, not from the live sessions (a
+  wave's steps take a slot and give it back between two steps): 2 − Σ min(cap, number of repositories
+  of the wave that still have lots). Never raise `--max-sessions` above two to speed a wave up.
 - **Never two subagents in the same repository at the same time**, and the lead does not commit in a
   repository where a subagent is working.
 - **Deliveries and `raf ux` / `raf review` verdicts are done by the lead, one project at a time** —
@@ -35,11 +41,12 @@ progress, then drift that blocks a delivery, then ready quick wins. **Stop and w
 ## 2. Delegation
 
 The default way to delegate is **`cadence orchestrate`** (section 2b): a program, not a conversation, that runs
-one fresh short session per step. When the lead delegates by hand, the brief is the template
-`templates/orchestrate/implement.md` of the cadence package — the single source, tested; `cadence
-orchestrate --dry-run <project>:<lot>` writes it rendered for the lot. The lead runs
-`cd <project> && raf start <lot>`, fills `{{chemin}}`, `{{lot}}`, `{{titre}}` and `{{objectif}}` (what done
-looks like, from the human's words), and keeps the rest verbatim.
+one fresh short session per step; the wave runs from a frozen copy of the cadence package, so it can orchestrate cadence itself and its templates can be edited meanwhile. When the lead delegates by hand, the brief is the template
+`templates/orchestrate/implement.md` of the cadence package — the single source, tested. The lead runs
+`cd <project> && raf start <lot>`, then starts from the brief written by `cadence orchestrate --dry-run
+<project>:<lot>`: it is already rendered (`{{chemin}}`, `{{lot}}`, `{{titre}}`, `{{objectif}}` and `{{news}}`,
+the News instruction of a `visible` lot, are filled in; it names no wave Playwright directory — a hand delegation has none — so the screenshot goes under the OS temp directory, then into `docs/nouveautes/captures/`). The lead only adjusts the goal to what done looks
+like (the human's words) and keeps the rest verbatim.
 
 A lot that adds or changes a screen is `visible`: after the implementation, have the
 `ux-reviewer` agent review it (give it the URL or the way to run the app) and bring its verdict and
@@ -57,7 +64,9 @@ cadence orchestrate <project>:<lot> <project>:<lot>@haiku … [--budget 2M]
 `cadence orchestrate --dry-run …` first when a precondition is in doubt. The program, not the lead, runs
 for each lot a fresh short session per step — implementation (Sonnet), UX review if the lot is `visible`
 and the project declares how to see its app (`orchestrate.ux` in `cadence.yaml`), code review last
-(Opus, the `code-reviewer` agent), a correction in a new session if the review is not compliant (two
+(Opus, the `code-reviewer` agent; Sonnet, with no pass on the minor findings, for a lot whose estimate is
+≤ 0.25 d — `orchestrate.review` in `cadence.yaml`; a blocker or major finding still brings a correction and an
+Opus review), a correction in a new session if the review is not compliant (two
 passes at most) — and records `raf review` itself when the code review is compliant. The state is in
 `.cadence/runs/<wave>/`, not in this conversation. `@haiku` only when the human writes it, for a
 mechanical lot. Exit code: 0 all ready · 1 some lots handed back · 2 refused before acting · 3 wave
@@ -67,7 +76,7 @@ What the orchestrator does **not** do, and stays with the lead: choose the lots
 questions back (`--resume --answer <project>:<lot> "…"`), look at the UX reviewer's captures and record
 `raf ux` (the orchestrator reports its verdict, it never records it), re-verify (section 3, point 2),
 `raf done`, push and deliver. Minor findings and proposed sub-tasks come back in the table: adding them to
-the plan is the lead's decision. If an orchestrated wave is running in a repository, do not commit there
+the plan is the lead's decision. A minor finding becomes a lot of its own only if it describes an observable bug (a wrong output, a crash, a measured regression); otherwise it stays a note of the originating lot, so that a review never feeds the next one. If an orchestrated wave is running in a repository, do not commit there
 and do not deliver it (`cadence deliver` refuses).
 
 ## 3. Check

package/templates/orchestrate/fix-minors.md

@@ -17,6 +17,9 @@ Minor choices to settle yourself, writing the alternative you did not take:
 a spacing, colour or label value when a measurement or a rule justifies it; the URL of a link (the most general official page if a precise one is not certain);
 a News entry: only if a finding asks for it; a written rule of the project's CLAUDE.md (apply it); who launches the review or UX pass (never the session: the program and the lead do).
 "not my job to touch the plan" is not a question: say it in the report.
+Never stop to ask about how to organise your own work (split or squash a commit, whether to continue): decide, list it under "choix", go on. A finding you contest is noted under "choix" with the evidence, not raised to the lead.
 You are one short session of an orchestrated wave: do not launch subagents (the Agent tool is disabled).
 Give your final report as the structured output (commits, tests, build, what you could not verify, choices).
 {{reponse}}
+{{captures}}
+Browser (Playwright): if a Playwright MCP server is available in this session, it was launched by the orchestrator with its own output directory, in the orchestrator's run directory outside the repository: give screenshots, snapshots and traces a relative file name only (e.g. `page-home.png`), they land there. Never an absolute path, never the `--output-dir` option (the server's launch argument, which a session cannot set). If no such server is available, do not install or start one; if you use the Playwright CLI, write its outputs under the OS temp directory (or the temporary folder the project's CLAUDE.md names), never inside the repository, which must stay clean.

package/templates/orchestrate/fix.md

@@ -16,6 +16,10 @@ otherwise it is a choice: decide, write the alternative you did not take, go on.
 a spacing, colour or label value when a measurement or a rule justifies it; the URL of a link (the most general official page if a precise one is not certain);
 a News entry: only if a finding asks for it; a written rule of the project's CLAUDE.md (apply it); who launches the review or UX pass (never the session: the program and the lead do).
 "not my job to touch the plan" is not a question: say it in the report.
+Never stop to ask about how to organise your own work (split or squash a commit, order of the sub-parts, whether to continue, "I have no question"): decide, list it under "choix", go on. Leave "questions" empty rather than writing a placeholder such as "no question".
+A finding you contest (it describes a state older than the code, or you think it wrong) is not a question and not a reason to stop: do not ask the lead to arbitrate. Write it under "choix" with the evidence (the command, the line, the commit), fix what is right, go on; the next fresh review re-reads it.
 You are one short session of an orchestrated wave: do not launch subagents (the Agent tool is disabled).
 Give your final report as the structured output (commits, tests, build, what you could not verify, choices, questions).
 {{reponse}}
+{{captures}}
+Browser (Playwright): if a Playwright MCP server is available in this session, it was launched by the orchestrator with its own output directory, in the orchestrator's run directory outside the repository: give screenshots, snapshots and traces a relative file name only (e.g. `page-home.png`), they land there. Never an absolute path, never the `--output-dir` option (the server's launch argument, which a session cannot set). If no such server is available, do not install or start one; if you use the Playwright CLI, write its outputs under the OS temp directory (or the temporary folder the project's CLAUDE.md names), never inside the repository, which must stay clean.

package/templates/orchestrate/implement.md

@@ -5,14 +5,16 @@ Rules: test first; commit each sub-part as soon as its tests pass, with explicit
 `git add -A` or `commit -a`), and a message that cites the lot (`feat({{lot}}): …`); run the project's
 full test suite and build before reporting; do not push, deliver, run `raf done`, `raf ux` or
 `raf review`.
+Documentation: the project's README (and its usage documentation) describes the behaviour you deliver, updated in the same commits, like the CHANGELOG — a README that does not follow your change is a major finding of the review.
 Decide minor interpretation questions yourself (the wording of a message, a name, a default, the
 reading of an ambiguous line of the lot) and list each one under "choix" in your report, with the
 alternative you did not take — the reviewer re-reads them. Stop and ask (under "questions") only on a real blocker.
 A question is legitimate only if it names what it would change: the scope of the lot, the architecture, or a costly rollback (data, production, public API), AND the plan, its notes and the project's CLAUDE.md do not settle it;
 otherwise it is a choice: decide, write the alternative you did not take, go on. Minor choices to settle yourself:
 a spacing, colour or label value when a measurement or a rule justifies it; the URL of a link (the most general official page if a precise one is not certain);
-a News entry for a visible lot (yes, always); a written rule of the project's CLAUDE.md (apply it); who launches the review or UX pass (never the session: the program and the lead do).
+a written rule of the project's CLAUDE.md (apply it); who launches the review or UX pass (never the session: the program and the lead do).
 "not my job to touch the plan" is not a question: say it in the report.
+Never stop to ask about how to organise your own work (split or squash a commit, order of the sub-parts, whether to continue, "I have no question"): decide, list it under "choix", go on. Leave "questions" empty rather than writing a placeholder such as "no question".
 If the lot's commits already cover its open sub-tasks, do not ask whether to continue: make no commit and say so
 in your report (the review that follows re-reads those commits). If they do not cover them all, implement the rest.
 Report: commits (sha + subject), tests and build results with their numbers, what you could not
@@ -21,5 +23,7 @@ verify, choices made, open questions.
 You are one short session of an orchestrated wave: do not launch subagents (the Agent tool is disabled).
 Give your final report as the structured output, not as free text. If the plan is kept by the project's own tool
 (read-only for `raf`), use that tool's commands named in the project's CLAUDE.md, never `raf start|done|note`.
+{{news}}
 {{commits}}
 {{reponse}}
+Browser (Playwright): if a Playwright MCP server is available in this session, it was launched by the orchestrator with its own output directory, in the orchestrator's run directory outside the repository: give screenshots, snapshots and traces a relative file name only (e.g. `page-home.png`), they land there. Never an absolute path, never the `--output-dir` option (the server's launch argument, which a session cannot set). If no such server is available, do not install or start one; if you use the Playwright CLI, write its outputs under the OS temp directory (or the temporary folder the project's CLAUDE.md names), never inside the repository, which must stay clean.

package/templates/orchestrate/precheck.md

@@ -0,0 +1,10 @@
+Pre-check for lot `{{lot}}` — "{{titre}}" — of the repository `{{chemin}}`, as the read-only pre-check reader.
+Question: is the deliverable of this lot ALREADY in the repository (done by another lot, or by a correction)?
+Goal of the lot: {{objectif}}
+Read the lot, its notes and sub-tasks in the plan (`docs/plan/raf.yaml`, or the file named by `plan:` in `cadence.yaml`),
+then look for the deliverable in the code and tests (`git log`, `grep`, reading the files the lot names). Do not
+implement anything and do not run the full test suite: this is a quick look.
+Answer `oui` only when every part of the lot is present, with a proof for each (file:line or commit sha); `partiel` when
+some parts are present (say which); `non` otherwise. When in doubt, answer `non`: an implementation session follows.
+You are read-only: do not modify, commit, push or run `raf start|done|note|review|ux`. Do not launch subagents.
+Give your report as the structured output: `dejaPresent` (oui | partiel | non), `preuves` (the proofs), `resume` (one sentence).

package/templates/orchestrate/review-recheck.md

@@ -4,7 +4,9 @@ treated them. Check that the minor findings fixed are fixed, that the fixes brok
 rest of the lot is still sound: read the diff yourself from the commits that cite the lot
 (`raf commits {{lot}}`, or `git log`), run the checks, report real defects only. A new minor finding
 is reported, not a reason to ask for another pass. This is a code review only.
+{{checks}}
 {{choix}}
+A proposed sub-task describes an observable bug (a wrong output, a crash, a measured regression); any other minor finding stays a note of this lot, not a sub-task.
 You are read-only: do not modify, commit, push or run `raf review|ux|done`. Do not launch subagents.
 Give your report as the structured output: counts of blocking / major / minor findings, each finding
 (severity, file, line, text), proposed sub-tasks, what you could not verify, and the one-line verdict