@sylad/cadence 0.11.0 → 0.13.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/state.js

@@ -5,7 +5,9 @@ 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 };
 }
 export const lotKey = (project, lot) => `${project}:${lot}`;
-const lotFile = (project, lot) => `${project}--${lot}.json`;
+/** Nom de dossier d'un lot dans la vague : le « / » d'un id de sous-tâche (`Q4/accueil-4-ux12`) devient « __ » ; un id sans « / » est inchangé. */
+export const lotSlug = (project, lot) => `${project}--${lot.split('/').join('__')}`;
+const lotFile = (project, lot) => `${lotSlug(project, lot)}.json`;
 function atomicWrite(file, data) {
     const tmp = `${file}.${process.pid}.tmp`;
     writeFileSync(tmp, `${JSON.stringify(data, null, 2)}\n`);
@@ -64,7 +66,7 @@ export class RunStore {
         return existsSync(join(RunStore.runsDir(launchDir), id, 'wave.json')) ? new RunStore(launchDir, id) : null;
     }
     lotDir(project, lot) {
-        const d = join(this.dir, `${project}--${lot}`);
+        const d = join(this.dir, lotSlug(project, lot));
         mkdirSync(d, { recursive: true });
         return d;
     }

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

@@ -51,6 +51,13 @@ export class Plan {
     }
     /** Un plan lu dans un autre format ne change pas : sa lecture et le motif de ses références sont gardés. */
     foreign;
+    /**
+     * Un plan en lecture seule dont `fields` ne déclare pas de champ `public` n'a pas de titre public à poser ni à lire,
+     * sauf si l'outil écrit déjà la clé `public` sous son propre nom sur un lot.
+     */
+    get hasPublicField() {
+        return !this.settings.format || !!this.settings.format.fields.public || this.read().lots.some((l) => l.public !== undefined);
+    }
     get readonly() {
         return !!this.settings.format;
     }
@@ -122,6 +129,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.13.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
@@ -48,16 +55,33 @@ proposed sub-tasks back to the human.
 ### 2b. A wave through `cadence orchestrate`
 
 Once the human has chosen the lots, the lead runs, **in the background** (it is notified at the end; no
-silent wait, no polling loop — `cadence orchestrate --status` shows where the wave is):
+silent wait, no polling loop — `cadence orchestrate --status` shows where the wave is, and the follow-up below pushes each transition):
 
 ```sh
-cadence orchestrate <project>:<lot> <project>:<lot>@haiku … [--budget 2M]
+cadence orchestrate <project>:<lot> <project>:<lot>@haiku … --wave <id> [--budget 2M]
 ```
 
+**Make the wave visible to the human.** Name the background task after what it runs — « vague `<id>` :
+`<project>:<lot>`, … » (its `description`), so the task list says which projects and lots, not just « a task
+is running » — and pass `--wave <id>` (e.g. `2026-10-08-1030`) so its state folder is known in advance. Right after
+starting it, arm **one follow-up** (the Monitor tool) on the wave's journal, which holds one line per transition (lot → new
+state, question, ready, handed back). The final table is not in the journal: it arrives with the background task's end notification, at which point stop the follow-up (it never ends by itself; a later `--resume` writes to the same journal):
+
+```sh
+tail -n +1 -F .cadence/runs/<id>/journal.log     # from the folder the wave was launched in
+```
+
+Each line it prints reaches this conversation as it happens: relay it to the human in one short sentence, and
+bring a question back at once (`--resume --answer`). That follow-up replaces any waiting loop: still no polling,
+no `sleep`. The human can also watch from a terminal with `cadence orchestrate --status --watch` (table refreshed
+every 10 s, `--interval <s>` to change it; it stops by itself when no wave is running).
+
 `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 +91,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 (only in an orchestrated wave: a brief delegated by hand has none), the orchestrator launched it 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 (only in an orchestrated wave: a brief delegated by hand has none), the orchestrator launched it 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.