@sylad/cadence 1.14.1 → 1.15.1

package/.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
     {
       "name": "cadence",
       "description": "Session start and close rituals driven by a versioned plan (raf), and deliveries proven by their effect. Needs the cadence CLI (npm i -g @sylad/cadence).",
-      "version": "1.14.1",
+      "version": "1.15.1",
       "source": "./",
       "author": {
         "name": "Sylvain Ladoire"

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "cadence",
   "description": "A repo-native working method: session start and close rituals driven by a versioned plan (raf), deliveries proven by their effect, and three reviewer agents (UX, code, QA).",
-  "version": "1.14.1",
+  "version": "1.15.1",
   "author": { "name": "Sylvain Ladoire" },
   "homepage": "https://github.com/Sylad/cadence",
   "repository": "https://github.com/Sylad/cadence",

package/README.md

@@ -17,6 +17,12 @@ raf add "My first lot" --estimate 1
 
 Then `raf start L1`, commit with `feat(L1): …`, `raf now` to see where you are, `raf done L1` when it is finished.
 
+## Lead several projects in 10 minutes
+
+A parent folder, a plan in each project, a `/cadence:lead` session that picks the lots, a wave that does the work.
+[docs/quickstart.md](docs/quickstart.md) goes from install to the first wave, and lists the usual stops.
+Something broken or missing? [Open an issue](https://github.com/Sylad/cadence/issues/new/choose).
+
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="docs/cycle-vague-dark.svg">
   <img alt="A lot goes through spec, mockup, accept, implement, review, ux and deliver; the lead picks the lots, answers the questions, re-verifies and delivers" src="docs/cycle-vague-light.svg">

package/dist/audit.js

@@ -149,6 +149,9 @@ export function audit(plan, root, newsDir, today, opts = {}) {
     const linked = exemptPlanOnly(linkCommits(lots, planCommits(plan, root, { since: auditSince(plan, opts.since) }), plan.refs), plan, root);
     // L'inactivité se mesure sur tout l'historique, pas seulement la fenêtre --since.
     const all = linkCommits(lots, planCommits(plan, root), plan.refs);
+    // Un commit acquitté (`raf ignore`) qui cite des lots connus ne compte pour aucun : ni commencé, ni actif, ni à relire.
+    for (const [id, cs] of all.byLot)
+        all.byLot.set(id, cs.filter((c) => !isAcknowledged(plan, c)));
     // Planifier un lot (commit qui ne touche que le plan) n'est pas y travailler : un lot « todo »
     // cité seulement par de tels commits n'a pas à être démarré. Ni par des commits antérieurs à
     // l'adoption du plan : citer un identifiant n'engageait alors à rien.
@@ -201,10 +204,10 @@ export function docSyncIssues(plan, root, byLot) {
         .filter((l) => l.status === 'doing' || (l.status === 'done' && !!since && !!l.finished && l.finished >= since))
         .flatMap((l) => docSyncGaps(sync, filesOf(root, workCommits(plan, root, byLot.get(l.id) ?? []))).map((g) => ({ message: gapMessage(l.id, g) })));
 }
-/** Commits qui portent du travail sur un lot : ni antérieurs à l'adoption du plan, ni réduits au plan, ni une simple version. */
+/** Commits qui portent du travail sur un lot : ni antérieurs à l'adoption du plan, ni acquittés (`raf ignore`), ni réduits au plan, ni une simple version. */
 function workCommits(plan, root, commits) {
     const adopted = plan.since;
-    return commits.filter((c) => (!adopted || c.day >= adopted) && !isPlanOnly(c.sha, plan, root) && !isReleaseOnly(c.sha, root));
+    return commits.filter((c) => (!adopted || c.day >= adopted) && !isAcknowledged(plan, c) && !isPlanOnly(c.sha, plan, root) && !isReleaseOnly(c.sha, root));
 }
 /** Commits liés à un lot, du plus récent au plus ancien, avant tout tri : commits de plan et d'avant l'adoption compris. */
 export function lotCommits(plan, root, lotId) {

package/dist/cli.js

@@ -61,7 +61,7 @@ const HELP = `raf — plan « reste à faire » versionné dans le dépôt, reli
   raf now               ce qui est en cours, la suite, les derniers terminés
   raf list [--status todo|doing|done|dropped]
   raf check [--since date] [--idle 7]   (défaut : date « since » du plan) code 1 s'il y a des écarts
-  raf ignore <sha> | "<sujet exact>" [--reason texte]   acquitte un commit sans lot (ou citant un id inconnu) sans réécrire l'historique ; raf check --ignored les liste
+  raf ignore <sha> | "<sujet exact>" [--reason texte]   acquitte un commit sans lot, citant un id inconnu ou des lots sans y travailler, sans réécrire l'historique ; raf check --ignored les liste
   raf docs-ok <lot> --reason texte   acquitte l'écart docs.sync d'un lot (documentation en retard) avec la raison pour laquelle la documentation reste telle quelle ; lu par raf check et par orchestrate, qui ne rend jamais prêt un lot avec un écart ouvert
   raf gantt [-o .cadence/gantt.html]
   cadence config set <clé> <valeur> --all [--dry-run] [--depth n]   pose la même clé dans le cadence.yaml de chaque projet du dossier (ceux de lead tour), commentaires et ordre gardés, un lot de config qui la cite (raf add + start) et un commit à chemin explicite par projet ; ne pousse pas ; liste ce qui est fait et sauté (dépôt sale, déjà posée, plan en lecture seule) ; s'arrête sur une config qui ne se relit pas
@@ -448,6 +448,9 @@ function dispatch(argv, io) {
                 if (lot.visible && !loadEntries(newsDir).some((e) => e.lots.includes(lot.id))) {
                     io.out(`${lot.id} est visible : écrire l'entrée : cadence news new ${lot.id}`);
                 }
+                const uncommitted = uncommittedPlanCommand(plan, root, lot.id, planConfig?.commit);
+                if (uncommitted)
+                    io.out(uncommitted);
             }
             return 0;
         }
@@ -810,6 +813,23 @@ function knownLot(plan, id, subtask) {
         throw new RafError(id.includes('/') ? `${subtask} : ${id}` : `lot inconnu : ${id}`);
     return lot;
 }
+/**
+ * `raf done` écrit le plan et ne le commite jamais (voulu : raf n'a pas de réglage qui commite, docs/raf.md) : la commande de commit du plan et des fichiers
+ * que `plan.onWrite` produit, au gabarit `plan.commit` du projet (L371). Null hors d'un dépôt git ou quand rien n'est à commiter.
+ */
+function uncommittedPlanCommand(plan, root, lot, template) {
+    const repo = gitRoot(root);
+    if (!repo)
+        return null;
+    // Seuls les chemins que git voit modifiés : `git add` d'un chemin absent ou ignoré est fatal.
+    const paths = dirtyPaths(repo, [relative(repo, plan.path), ...plan.files, ...plan.produced]);
+    if (paths.length === 0)
+        return null;
+    const quote = (t) => (/^[\w./-]+$/.test(t) ? t : `'${t.replaceAll("'", "'\\''")}'`);
+    const message = planCommitMessage(template, { lot, action: PLAN_ACTIONS.done });
+    const list = paths.map(quote).join(' ');
+    return `plan non commité : raf ne commite jamais (voulu, ce n'est pas un réglage), à commiter :\n  git add -- ${list} && git commit -m ${quote(message)} -- ${list}`;
+}
 function describe(l, commits) {
     const bits = [`${l.estimate} j`];
     if (commits)

package/dist/orchestrate/changelog-merge.js

@@ -47,6 +47,8 @@ function onlyAdds(base, side) {
             i++;
     return i === base.length;
 }
+/** `text` porte l'entrée `e` entière, sur ses propres lignes : « - Fix typo » n'est pas dans « - Fix typo in README ». */
+const hasEntry = (text, e) => `\n${text}\n`.includes(`\n${e}\n`);
 /** Un côté qui n'a pas bougé laisse l'autre gagner ; deux côtés qui ont bougé de la même façon aussi ; sinon, pas de réponse. */
 function pick(base, ours, theirs) {
     if (ours === theirs)
@@ -78,22 +80,27 @@ export function mergeUnreleased(base, ours, theirs, start) {
     const st = start === undefined ? null : split(start);
     const startEntries = new Set([...(st ? (sections(st.block)?.values() ?? []) : [])].flat());
     const own = new Set(start === undefined || !st ? [] : [...bs.values()].flat().filter((e) => !startEntries.has(e)));
+    // Une entrée de base que ours range sous une version publiée (la branche a été publiée pendant la vie du lot) n'a pas été retirée : elle a changé de place.
+    // Seule une entrée de base compte, entière : une entrée nouvelle de theirs qui est un bout d'une entrée publiée n'est pas la même, elle reste au lot.
+    // Les entrées du lot (`own`) ne comptent pas dans l'ordre de ours : l'union d'un commit précédent les y a recasées en fin de section.
+    const baseEntries = new Set([...bs.values()].flat());
+    const released = (e) => baseEntries.has(e) && o.tail !== b.tail && hasEntry(o.tail, e) && !hasEntry(b.tail, e);
     for (const [title, entries] of bs) {
         const kept = entries.filter((e) => !own.has(e));
-        if (!onlyAdds(kept, (os.get(title) ?? []).filter((e) => !own.has(e))) || !onlyAdds(entries, os.get(title) ?? []) || !onlyAdds(kept, ts.get(title) ?? [])) {
+        if (!onlyAdds(kept.filter((e) => !released(e)), (os.get(title) ?? []).filter((e) => !own.has(e))) || !onlyAdds(kept, ts.get(title) ?? [])) {
             return null;
         }
     }
     const titles = [...new Set([...os.keys(), ...ts.keys()])];
     titles.sort((x, y) => rank(x) - rank(y));
-    const body = titles.map((title) => {
-        const entries = [...new Set([...(os.get(title) ?? []).filter((e) => !own.has(e)), ...(ts.get(title) ?? [])])];
-        return `### ${title}\n\n${entries.join('\n')}\n`;
+    const body = titles.flatMap((title) => {
+        const entries = [...new Set([...(os.get(title) ?? []).filter((e) => !own.has(e)), ...(ts.get(title) ?? []).filter((e) => !released(e))])];
+        return entries.length ? [`### ${title}\n\n${entries.join('\n')}\n`] : [];
     });
     return `${head}\n\n${body.join('\n')}\n${tail}`;
 }
 /** Entrées du bloc `[Unreleased]` de `text`, par section ; null sans bloc ou avec du texte hors entrée. */
-function unreleasedEntries(text) {
+export function unreleasedSections(text) {
     const s = split(text);
     return s ? sections(s.block) : null;
 }
@@ -105,7 +112,7 @@ function unreleasedEntries(text) {
  */
 export function moveToUnreleased(rebased, lotTip, start, main) {
     const [r, mainSplit] = [split(rebased), split(main)];
-    const [tip, was] = [unreleasedEntries(lotTip), unreleasedEntries(start)];
+    const [tip, was] = [unreleasedSections(lotTip), unreleasedSections(start)];
     const [now, published] = [sections(r?.block ?? []), mainSplit ? mainSplit.tail : ''];
     if (!r || !tip || !was || !now)
         return null;
@@ -115,9 +122,9 @@ export function moveToUnreleased(rebased, lotTip, start, main) {
     const added = new Map();
     for (const [title, entries] of tip) {
         for (const e of entries) {
-            if (known.has(e) || published.includes(e) || (now.get(title) ?? []).includes(e) || !tail.includes(e))
+            if (known.has(e) || hasEntry(published, e) || (now.get(title) ?? []).includes(e) || !hasEntry(tail, e))
                 continue;
-            tail = tail.replace(`${e}\n`, '');
+            tail = tail.replace(`\n${e}\n`, '\n');
             added.set(title, [...(added.get(title) ?? []), e]);
             moved++;
         }
@@ -131,3 +138,50 @@ export function moveToUnreleased(rebased, lotTip, start, main) {
     const body = titles.map((title) => `### ${title}\n\n${(now.get(title) ?? []).join('\n')}\n`);
     return { text: `${r.head}\n\n${body.join('\n')}\n${tail}`, moved };
 }
+/**
+ * Une entrée finale par lot (L369) : après le rebase, le `[Unreleased]` ne porte du lot que ses entrées du sommet de sa branche. Les `intermediates` — les
+ * entrées que ses commits successifs ont écrites puis réécrites, absentes du sommet comme de ses versions publiées — en sont retirées (sous `[Unreleased]` comme sous une version), à moins
+ * que `main` ne les porte aussi : elles sont alors à elle. Une entrée du sommet absente du texte (ni sous `[Unreleased]`, ni sous une version, ni déjà publiée
+ * sur `main`) y est remise sous sa section. `lotTip`, `start`, `main` : comme pour `moveToUnreleased`. Rend le texte corrigé, ou null quand il n'y a rien à
+ * changer (ou que le fichier n'a pas la forme attendue).
+ */
+export function settleLotEntries(rebased, lotTip, start, main, intermediates) {
+    const [r, mainSplit] = [split(rebased), split(main)];
+    const [tip, was] = [unreleasedSections(lotTip), unreleasedSections(start)];
+    const now = sections(r?.block ?? []);
+    if (!r || !mainSplit || !tip || !was || !now)
+        return null;
+    const mainOwn = new Set([...(sections(mainSplit.block)?.values() ?? [])].flat());
+    const known = new Set([...was.values()].flat());
+    const final = new Set([...tip.values()].flat());
+    // Une entrée que le sommet du lot porte sous une version (le lot l'a publiée lui-même) est finale, pas intermédiaire.
+    const tipTail = split(lotTip)?.tail ?? '';
+    const stale = intermediates.filter((e) => !final.has(e) && !hasEntry(tipTail, e) && !mainOwn.has(e) && !hasEntry(mainSplit.tail, e));
+    let changed = false;
+    for (const [title, entries] of now) {
+        const kept = entries.filter((e) => !stale.includes(e));
+        if (kept.length !== entries.length)
+            changed = true;
+        now.set(title, kept);
+    }
+    let tail = r.tail;
+    for (const e of stale) {
+        if (hasEntry(tail, e)) {
+            tail = tail.replace(`\n${e}\n`, '\n');
+            changed = true;
+        }
+    }
+    const present = (e) => [...now.values()].some((v) => v.includes(e)) || hasEntry(tail, e) || hasEntry(mainSplit.tail, e);
+    for (const [title, entries] of tip) {
+        for (const e of entries.filter((x) => !known.has(x) && !present(x))) {
+            now.set(title, [...(now.get(title) ?? []), e]);
+            changed = true;
+        }
+    }
+    if (!changed)
+        return null;
+    tail = tail.replace(/^### .+\n\n(\n|$)/gm, '');
+    const titles = [...now.keys()].filter((t) => (now.get(t) ?? []).length > 0).sort((x, y) => rank(x) - rank(y));
+    const body = titles.map((title) => `### ${title}\n\n${(now.get(title) ?? []).join('\n')}\n`);
+    return `${r.head}\n\n${body.join('\n')}\n${tail}`;
+}

package/dist/orchestrate/command.js

@@ -26,7 +26,7 @@ import { maquetteText } from './maquette.js';
 import { costlyHypotheses, specScreen, specText } from './spec.js';
 import { fichesDuDossier } from '../spec.js';
 import { candidates, parsePriority, parseUntil, readPriority, stopReason } from './continue.js';
-import { precheckNothingToFind, Budget, ESCALATION_RESERVE, DROPPED, STOP_REQUESTED, MAX_PASSES, REVIEW_RESERVE, budgetStep, heldForEscalation, lotSpent, MAX_PASSES_CONVERGING, briefName, countInterrupted, planNoteHandBack, HYPOTHESES_HANDBACK, handBackDroppedQuestions, needsPrecheck, workDir } from './cycle.js';
+import { precheckNothingToFind, Budget, ESCALATION_RESERVE, DROPPED, STOP_REQUESTED, MAX_PASSES, REVIEW_RESERVE, budgetStep, heldForEscalation, lotSpent, MAX_PASSES_CONVERGING, briefName, countInterrupted, planNoteHandBack, leadReviewedHandBack, HYPOTHESES_HANDBACK, handBackDroppedQuestions, needsPrecheck, workDir } from './cycle.js';
 import { canInstallPrePush, installPrePush, removePrePush, snapshot } from './guard.js';
 import { buildArgs, buildLocalArgs, killSessions, MODEL_ALIASES, mcpServersFor, readAgents, realClaude } from './launch.js';
 import { activeLock, REPO_LOCK, releaseLock, takeLock } from './lock.js';
@@ -1432,6 +1432,8 @@ async function resume(args, argv, io, deps, launch, today) {
     }
     // --resume --integrate projet:lot (L279, R27) : un lot rendu à l'étape d'intégration (next: integrate) n'est rejoué que si le lead le nomme. Ni --resume seul, ni --drop, --answer ou --budget ne le rejouent.
     const integ = [];
+    // L370 : un lot rendu hors de l'intégration que le lead a fait corriger puis revoir hors vague (revue conforme au dernier commit du worktree) est repris à l'intégration avec ce verdict.
+    const leadReviewed = new Map();
     const budgeted = args.lotBudgets.map((b) => lots.filter((x) => x.lot === b.lot && (b.project ? x.project === b.project : true))).filter((m) => m.length === 1).map((m) => m[0]);
     for (const t of args.integrate) {
         const matches = lots.filter((x) => x.lot === t.lot && (t.project ? x.project === t.project : true));
@@ -1451,6 +1453,15 @@ async function resume(args, argv, io, deps, launch, today) {
             refusals.push(`${opt} ${key} : lot aussi visé par --answer`);
         else if (budgeted.includes(l))
             refusals.push(`${opt} ${key} : lot aussi visé par --budget`);
+        else if (!t.replay && l.next !== 'integrate' && (() => {
+            // La revue du lead est écrite par `raf review` lancé dans le worktree : c'est le plan du worktree qui la porte, pas celui du dépôt principal.
+            const tree = lotTreeDir(store.dir, l.project, l.lot, l.repo);
+            const r = existsSync(join(tree, '.git')) ? leadReviewedHandBack(l, planLoader(tree)(), tree) : null;
+            if (r)
+                leadReviewed.set(l, r);
+            return r;
+        })())
+            integ.push(l);
         else if (l.status !== 'handed-back' || (l.next !== 'integrate' && !(t.replay && planNoteHandBack(l))))
             refusals.push(`${opt} ${key} : le lot n'est pas rendu ${t.replay ? "à l'étape d'intégration ni sur une écriture de plan refusée" : "à l'étape d'intégration"} (${l.status}, étape ${l.next ?? 'aucune'} : ${l.outcome ?? 'sans cause'})`);
         else
@@ -1545,12 +1556,20 @@ async function resume(args, argv, io, deps, launch, today) {
     }
     for (const l of integ) {
         const k = lotKey(l.project, l.lot);
+        const lead = leadReviewed.get(l);
+        if (lead) {
+            // La revue du lead tient lieu de revue du lot : le rebase reporte son verdict (même patch-id) ou joue la revue courte du diff rebasé.
+            l.next = 'integrate';
+            l.code = { conforme: true, bloquants: 0, majeurs: 0, mineurs: 0, verdict: lead.verdict, sousTaches: [], nonVerifie: [], head: lead.head };
+            l.verdict = lead.verdict;
+            l.constats = [];
+        }
         const planNote = l.next !== 'integrate'; // rendu sur une écriture de plan refusée (--replay) : le lot repart de l'étape gardée
         if (planNote && l.outcome?.startsWith(HYPOTHESES_HANDBACK))
             l.hypotheses = undefined; // les notes d'hypothèses se posent de nouveau (sans doublon) à l'entrée de l'étape
         l.status = 'suspended';
         l.outcome = null;
-        const text = planNote ? `écriture du plan reprise à l'étape ${l.next} (--resume --replay)` : 'intégration reprise (--resume --integrate)';
+        const text = lead ? `intégration reprise (--resume --integrate) : revue conforme du lead hors vague, ${lead.head.slice(0, 7)}` : planNote ? `écriture du plan reprise à l'étape ${l.next} (--resume --replay)` : 'intégration reprise (--resume --integrate)';
         store.journal(`${k} → suspended — ${text}`);
         io.out(`${k} → suspended — ${text}`);
     }

package/dist/orchestrate/cycle.js

@@ -2688,6 +2688,17 @@ const MINORS_HANDBACK = 'notes des mineurs de la revue de ';
  * (décision du lead du 24-10). Aucun champ d'état : la cause rendue le désigne.
  */
 export const planNoteHandBack = (l) => l.status === 'handed-back' && l.next !== null && l.next !== undefined && !!l.outcome && (l.outcome.startsWith(HYPOTHESES_HANDBACK) || l.outcome.startsWith(MINORS_HANDBACK));
+/**
+ * Un lot rendu hors de l'étape d'intégration (budget, revue non conforme…) que le lead a fait corriger puis revoir hors vague (L370) : sa revue de code du plan
+ * porte le dernier commit de travail du lot dans son worktree, donc rien n'a été commité après elle. Rend le sha relu et le verdict du lead, ou null.
+ */
+export function leadReviewedHandBack(l, plan, treeDir) {
+    if (l.status !== 'handed-back' || l.next === 'integrate' || planNoteHandBack(l) || !existsSync(join(treeDir, '.git')))
+        return null;
+    const review = plan.lots().find((x) => x.id === l.lot)?.review;
+    const tip = lotWork(plan, treeDir, l.lot)[0]?.sha;
+    return review?.commit && tip && review.commit === tip ? { head: tip, verdict: review.verdict } : null;
+}
 /** Une écriture de plan refusée rend le lot au lead ; en worktree, il garde l'étape atteinte pour la reprise (R26), sinon `stop` la vide comme avant. */
 function handBackPlan(c, why) {
     if (c.tree)
@@ -2750,6 +2761,8 @@ async function integrateLot(c) {
                     c.wave.log(`${key} CHANGELOG.md : conflit d'ajout pur résolu par union sous [Unreleased] (${rebased.changelog} commit(s))`);
                 if (rebased.kind === 'rebased' && rebased.moved > 0)
                     c.wave.log(`${key} CHANGELOG.md : ${rebased.moved} entrée(s) du lot replacée(s) sous [Unreleased], une publication a eu lieu pendant la branche`);
+                if (rebased.kind === 'rebased' && rebased.settled)
+                    c.wave.log(`${key} CHANGELOG.md : une entrée finale par lot, les versions intermédiaires du lot écartées`);
                 const tip = git(t.dir, 'rev-parse', 'HEAD');
                 if (tip !== reviewed) {
                     // Le rebase a changé les commits : tests et build rejoués au sommet rebasé, avant que la branche du dépôt ne bouge (R7).

package/dist/orchestrate/integrate.js

@@ -4,8 +4,10 @@ import { join } from 'node:path';
 import { gitCommonDir } from '../git.js';
 import { sharedStateDir } from '../state.js';
 import { activeLock, releaseLock, takeLock } from './lock.js';
-import { mergeUnreleased, moveToUnreleased } from './changelog-merge.js';
+import { mergeUnreleased, moveToUnreleased, settleLotEntries, unreleasedSections } from './changelog-merge.js';
 import { mutexFor } from './mutex.js';
+import { Plan } from '../plan.js';
+import { parseDocument } from 'yaml';
 import { git, gitFailure, tryGit } from './worktree.js';
 /** Verrou d'intégration d'un dépôt (L279, R10) : dans l'état commun aux worktrees, au format du verrou d'orchestration, sous un autre nom. */
 export const INTEGRATION_LOCK = 'orchestrate-integration.lock';
@@ -79,6 +81,48 @@ function resolveChangelog(work, start) {
         return false;
     }
 }
+/**
+ * Résout le conflit en cours quand c'est le plan seul et que le commit du lot rejoué n'y ajoute que des revues de lot (L370 : le `raf review` du lead dans
+ * le worktree) : le plan de la branche du dépôt est gardé, et chaque revue ajoutée est réécrite dessus par l'API du plan. Faux, sans rien toucher, si le
+ * commit change autre chose que des revues — un autre champ d'un lot, un lot ajouté ou retiré, ou la tête du plan hors `lots` (`acknowledged:` après un
+ * `raf ignore`, `reviewSince`, un réglage) : repris tel quel, le plan du dépôt perdrait ce changement sans message —, ou si la branche du dépôt a elle-même
+ * changé une de ces revues.
+ */
+function resolvePlan(work) {
+    const files = (tryGit(work, 'diff', '--name-only', '--diff-filter=U') ?? '').split('\n').filter(Boolean);
+    if (files.length !== 1)
+        return false;
+    const file = files[0];
+    try {
+        const stage = (n) => {
+            const text = run(work, 'show', `:${n}:${file}`);
+            writeFileSync(join(work, file), text);
+            const head = parseDocument(text).toJSON();
+            return { lots: Plan.load(join(work, file)).lots(), head: JSON.stringify({ ...(head ?? {}), lots: undefined }) };
+        };
+        const [b, o, t] = [stage(1), stage(2), stage(3)];
+        const [base, ours, theirs] = [b.lots, o.lots, t.lots];
+        if (t.head !== b.head)
+            return false;
+        const bare = (l) => JSON.stringify({ ...l, review: undefined });
+        const review = (l) => JSON.stringify(l?.review ?? null);
+        const added = theirs.filter((t) => review(t) !== review(base.find((b) => b.id === t.id)));
+        if (!added.length || theirs.length !== base.length || theirs.some((t) => bare(t) !== bare(base.find((b) => b.id === t.id) ?? { review: 1 })))
+            return false;
+        if (added.some((t) => review(ours.find((o) => o.id === t.id)) !== review(base.find((b) => b.id === t.id))))
+            return false;
+        writeFileSync(join(work, file), run(work, 'show', `:2:${file}`));
+        const plan = Plan.load(join(work, file));
+        for (const t of added)
+            plan.recordReview(t.id, t.review.verdict, t.review.date, t.review.commit ?? null, t.review.repos, t.review.reporte);
+        plan.save();
+        run(work, 'add', '--', file);
+        return true;
+    }
+    catch {
+        return false; // le fichier écrasé est restauré par le `rebase --abort` de l'appelant
+    }
+}
 /**
  * Après un rebase réussi : les entrées que le lot a ajoutées sous `[Unreleased]` et qu'une publication de la branche a laissées sous la version publiée
  * (git les y range sans conflit quand le bloc a été renommé) sont remises sous le `[Unreleased]` de la branche, dans un commit à part (L362). Rend leur nombre.
@@ -97,9 +141,33 @@ function moveOwnEntries(work, base, before, start) {
     run(work, 'commit', '--no-verify', '-q', '-m', 'docs: CHANGELOG — les entrées du lot replacées sous [Unreleased] (une publication a eu lieu pendant la branche)');
     return fixed.moved;
 }
+/** Lignes d'entrée de `text` sous `[Unreleased]` (une entrée sur plusieurs lignes : le bloc entier), ou aucune sans bloc `[Unreleased]` lisible. */
+const entriesOf = (text) => [...(unreleasedSections(text)?.values() ?? [])].flat();
+/**
+ * Après un rebase réussi : une seule entrée par lot, celle du sommet de sa branche (L369). Les entrées que les commits successifs du lot ont écrites sous
+ * `[Unreleased]` puis réécrites (absentes du sommet et du point de départ) sont retirées du résultat, celles du sommet qui y manquent remises, dans un commit
+ * à part. Rend vrai quand ce commit a eu lieu.
+ */
+export function settleOwnEntries(work, base, before, start) {
+    if (start === undefined || !existsSync(join(work, CHANGELOG)))
+        return false;
+    const [tip, main] = [tryGit(work, 'show', `${before}:${CHANGELOG}`), tryGit(work, 'show', `refs/heads/${base}:${CHANGELOG}`)];
+    if (tip === null || main === null)
+        return false;
+    const known = new Set(entriesOf(start));
+    const commits = (tryGit(work, 'rev-list', `${mergeBase(work, before, base)}..${before}`) ?? '').split('\n').filter(Boolean);
+    const written = commits.flatMap((c) => entriesOf(tryGit(work, 'show', `${c}:${CHANGELOG}`) ?? '')).filter((e) => !known.has(e));
+    const fixed = settleLotEntries(readFileSync(join(work, CHANGELOG), 'utf8'), tip, start, main, [...new Set(written)]);
+    if (fixed === null)
+        return false;
+    writeFileSync(join(work, CHANGELOG), fixed);
+    run(work, 'add', '--', CHANGELOG);
+    run(work, 'commit', '--no-verify', '-q', '-m', 'docs: CHANGELOG — une entrée finale par lot, celle du sommet de sa branche (les versions intermédiaires écartées)');
+    return true;
+}
 /**
  * Rebase le worktree `work` sur la branche `base` (R6). Une branche qui descend déjà du sommet de `base` n'a rien à rebaser (fast-forward pur : aucun sha ne
- * change). Un conflit d'ajout pur dans le CHANGELOG est résolu par union à chaque commit qui le porte (L314, `changelog` les compte). Tout autre conflit — ou
+ * change). Un conflit d'ajout pur dans le CHANGELOG est résolu par union à chaque commit qui le porte (L314, `changelog` les compte), un conflit du plan quand le commit n'y ajoute que des revues de lot (L370). Tout autre conflit — ou
  * tout autre échec du rebase — est abandonné (`rebase --abort`) : la branche du lot et son arbre restent tels qu'avant, la branche du dépôt n'a pas été
  * touchée, personne ne résout le conflit à l'aveugle.
  */
@@ -116,7 +184,7 @@ export function rebaseOnto(work, base) {
         let failure = first;
         // Chaque tour règle le commit sur lequel le rebase s'est arrêté ; un lot ne porte pas des centaines de commits, la borne évite seulement une boucle sans fin.
         for (let turn = 0;; turn++) {
-            if (turn >= 200 || !resolveChangelog(work, start)) {
+            if (turn >= 200 || !(resolveChangelog(work, start) || resolvePlan(work))) {
                 const files = (tryGit(work, 'diff', '--name-only', '--diff-filter=U') ?? '').split('\n').filter(Boolean);
                 tryGit(work, 'rebase', '--abort');
                 return { kind: 'conflict', files, detail: gitFailure(failure) };
@@ -132,7 +200,8 @@ export function rebaseOnto(work, base) {
         }
     }
     const moved = moveOwnEntries(work, base, before, start);
-    return { kind: 'rebased', before, after: git(work, 'rev-parse', 'HEAD'), changelog, moved };
+    const settled = settleOwnEntries(work, base, before, start);
+    return { kind: 'rebased', before, after: git(work, 'rev-parse', 'HEAD'), changelog, moved, settled };
 }
 /**
  * Patch-id stable (`git patch-id --stable`) du diff cumulé de `from` à `to` (R9) : le même diff reste le même quand le contexte se déplace, il change quand

package/dist/plan-commit.js

@@ -16,6 +16,8 @@ export const PLAN_ACTIONS = {
     started: 'démarré',
     hypotheses: (sujet) => `hypothèses de la fiche ${sujet} notées`,
     minors: (label) => `mineurs de la revue de ${label} notés`,
+    /** `raf done` ne commite pas : l'action de la commande de commit qu'il propose (L371). */
+    done: 'terminé',
     reviewRecorded: 'revue de code enregistrée',
     reviewNoted: 'revue de code notée',
     /** `spec green` (L366) : jamais la liste des tests rescellés, elle va dans le corps du commit (header-max-length de commitlint). */

package/docs/lead.md

@@ -90,6 +90,7 @@ picture, not its source.
 | The UX verdict is the human's unless `lead.ux: lead` (parent `cadence.yaml`, default `human`) | then the lead decides from the report and the captures, and brings any doubt to the human |
 | A session cannot ask the human anything | it stops and reports; the lead brings the question back |
 | Never push or deliver HEAD above a handed-back lot | HEAD holds code that was not reviewed |
+| A lot handed back for its budget or a non-compliant review that the lead had corrected outside the wave is integrated by `cadence orchestrate --resume --wave <wave> --integrate <project>:<lot>` (L370, [`--integrate`](orchestrate.md#one-worktree-per-lot-orchestrateworktrees-l279)): the fix is made in the kept worktree, then `raf review <lot> "conforme : …"` is run in that worktree and its plan committed there, after the last work commit of the lot; the program rebases, replays the checks, keeps the verdict or makes a short review, and advances the branch | never by hand (L367, 26-10), and never a review recorded in the main repository's plan: `--integrate` reads the worktree's plan and would keep refusing |
 | A plan kept by another tool is read-only for `raf` | its own commands record the lot's state |
 
 ## Exit codes

package/docs/orchestrate.md

@@ -574,12 +574,19 @@ nothing below applies and the wave behaves as before; any other value is refused
      entry of the replayed commit's parent that was not in the `CHANGELOG.md` at the branch's starting point (the merge-base with the repository's
      branch) was added by an earlier commit of the same lot, so the replayed commit may reword or remove it — its version wins, the earlier one is dropped
      from the repository's side — while an entry that was already there at the starting point, reworded, stays a conflict by hand. The
-     journal says `<project>:<lot> CHANGELOG.md : conflit d'ajout pur résolu par union sous [Unreleased] (<n> commit(s))`. Anything else — an entry that
-     **A release during the branch's life** (L362): when the repository's branch was released after the lot's branch was cut, its `## [Unreleased]` became
+     journal says `<project>:<lot> CHANGELOG.md : conflit d'ajout pur résolu par union sous [Unreleased] (<n> commit(s))`. **A release during the branch's life** (L362):
+     when the repository's branch was released after the lot's branch was cut, its `## [Unreleased]` became
      `## [x.y.z]` and git, merging without conflict, files the lot's entries under that published version. After the rebase the program moves the entries of
      the lot (those in its `[Unreleased]` and not in the `CHANGELOG.md` of the starting point) that landed in the published part, and were not already
      there on the repository's branch, back under the repository's `## [Unreleased]`, in a commit of its own (`docs: CHANGELOG — les entrées du lot replacées
-     sous [Unreleased] …`); the journal says `<project>:<lot> CHANGELOG.md : <n> entrée(s) du lot replacée(s) sous [Unreleased], …`.
+     sous [Unreleased] …`); the journal says `<project>:<lot> CHANGELOG.md : <n> entrée(s) du lot replacée(s) sous [Unreleased], …`. When the release and the
+     lot's addition touch the same lines, the conflict is resolved too (L369): an entry of the commit's parent that the repository's branch now keeps under a
+     published version was **moved by the release, not removed**, so it does not count as a removal and is not written again under `[Unreleased]`. Only an entry of the parent, whole, counts as moved: a new entry of the lot whose text is a fragment of a published one (« Fix typo » when the release carries « Fix typo in README ») is not that entry, it stays under `[Unreleased]`, and the same whole-entry match applies when the program looks for a lot's entry in the published part.
+     **One final entry per lot** (L369): the lot's commits may write then reword their entry several times (L360 on 2026-10-26: four contradictory entries
+     stacked). After the rebase the program lists the entries the lot's commits wrote under `[Unreleased]` that are neither at the starting point nor at
+     the lot's tip (nor under a version the tip itself carries: an entry the lot published itself is final), drops them from the result (under `[Unreleased]` and under a version), and puts back an entry of the tip that is missing, in a commit of
+     its own (`docs: CHANGELOG — une entrée finale par lot …`); an entry the repository's branch also carries is left alone. The union of an earlier replayed commit files the lot's entry at the end of its section; where the lot first put it (top of the section included) does not matter for the next replayed commit. The journal says
+     `<project>:<lot> CHANGELOG.md : une entrée finale par lot, les versions intermédiaires du lot écartées`. Anything else — an entry that
      was already there removed or reworded, free text under `[Unreleased]`, the rest of the
      file changed on both sides, another file in conflict with it — aborts the rebase and hands the lot back as above. The rebased commits differ, so
      steps 3 and 4 apply: tests replayed, and a short review since the patch-id changed;
@@ -615,7 +622,8 @@ nothing below applies and the wave behaves as before; any other value is refused
   fiche is replayed and counted once). `--replay` is refused for a lot handed back in any other way, with the same exit code and rules as `--integrate`. Refused (exit 2, before
   anything is written, like the other resume refusals): a lot unknown or named twice, also named by `--drop`, `--answer` or `--budget`, a lot that is not
   handed back at the integration step (`le lot n'est pas rendu à l'étape d'intégration (<status>, étape <step or aucune> : <cause>)`: a lot handed back for
-  review, tests or budget has `next` empty and takes the recovery path below), and, like any resume, a repository with a modified tracked file.
+  review, tests or budget has `next` empty and takes the recovery path below, unless the lead had it corrected and reviewed off the wave: next paragraph), and, like any resume, a repository with a modified tracked file.
+  **A lot handed back for its budget or a non-compliant review, that the lead had corrected and reviewed outside the wave (L370)** is accepted by `--resume --wave <wave> --integrate <project:lot>` too: the lead fixed it in the kept worktree, then recorded a compliant review with `raf review <lot> "…"` run in that worktree and committed the plan there (the review is read from the worktree's plan, not from the main repository's), and the recorded `commit` of that review is the **last work commit of the lot in its worktree** (no commit after the review; a review that predates a commit, or none, keeps the refusal above). The lot restarts at the integration step (`<project>:<lot> → suspended — intégration reprise (--resume --integrate) : revue conforme du lead hors vague, <sha>`) with the lead's verdict in place of the wave's review: rebase on the repository's branch, checks replayed, the verdict carried over when the diff is the same (same patch-id) or a short review of the rebased diff (the plan commit made in the worktree is part of that diff, so a short review is the usual case; if the lead also wrote on that lot in the repository's plan meanwhile — `raf note`, `raf add --parent` — the plan conflict of the rebase is settled by the program, which keeps the repository's plan and writes the lead's review back on it, provided the commit only adds lot reviews — nothing else on a lot, no lot added or removed, and nothing outside `lots` such as an `acknowledged:` entry from `raf ignore` or a head setting, which a kept repository plan would silently lose — and the repository did not change that review itself; any other plan conflict hands the lot back as before), then the advance. Handed back for another cause (acceptance lock, `HEAD` moved…), a lot that meets the condition is accepted the same way; `--replay` never takes this path. The lead no longer integrates by hand for it.
 - **A lot handed back outside the integration step** (non-compliant review, red tests, `HEAD` moved, plan touched, acceptance lock, quota…) keeps its worktree and its
   branch `cadence/<wave>/<project>--<lot>` but is not replayed by `--resume`. Its recovery path (L301) is **a new wave of the same lot** (`cadence orchestrate <project>:<lot>`):
   with the worktree mode on (`orchestrate.worktrees: true`), the new wave looks for the **most recent** (creation time noted by cadence) recognised branch `cadence/<other wave>/<project>--<lot>`

package/docs/overview.md

@@ -61,6 +61,7 @@ The two plugins are independent. `cadence@cadence` carries the rituals, which ca
 
 | Page | What it covers |
 |---|---|
+| [docs/quickstart.md](quickstart.md) | getting started as a lead of several projects, in 10 minutes: install, the parent folder, `raf init`, the tour, the first wave |
 | [docs/raf.md](raf.md) | the plan: commands, plan file, foreign plan formats, Gantt |
 | [docs/orchestrate.md](orchestrate.md) | waves of sessions: budgets, spec, accept and review steps, neighbouring repositories, one worktree per lot (`orchestrate.worktrees: true`, on in cadence's own `cadence.yaml`, off by default elsewhere; `--integrate`, `--replay`, `--remove-worktree`; recovery of a handed-back lot's branch and the `CHANGELOG.md` union at the integration are described there) |
 | [docs/deliver.md](deliver.md) | delivery: wait for CI, deploy, verify the effect |

package/docs/quickstart-dark.svg

@@ -0,0 +1,33 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1010 190" width="1010" height="190" role="img" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif" font-size="13" fill="#e6edf3">
+<title>One lead, several projects, one wave</title>
+<desc>A parent folder holds the projects alpha and beta, each with its own plan. The lead session reads their tour and you choose the lots. A wave of fresh sessions does the work, then you review and deliver.</desc>
+<defs><marker id="arq" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 z" fill="#8b949e"/></marker></defs>
+<rect width="1010" height="190" fill="#0d1117"/>
+<text x="20" y="22" font-weight="600" font-size="13.5" fill="#e6edf3">1. Parent folder</text>
+<rect x="20" y="32" width="220" height="140" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5" stroke-dasharray="5 4"/>
+<text x="130" y="52" text-anchor="middle" font-size="11.5" fill="#8b949e">atelier/ (not a repository)</text>
+<rect x="40" y="64" width="180" height="42" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="130" y="83" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">alpha</text>
+<text x="130" y="98" text-anchor="middle" font-size="11" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#8b949e">raf init · plan</text>
+<rect x="40" y="116" width="180" height="42" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="130" y="135" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">beta</text>
+<text x="130" y="150" text-anchor="middle" font-size="11" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#8b949e">raf init · plan</text>
+<text x="300" y="22" font-weight="600" font-size="13.5" fill="#e6edf3">2. The lead</text>
+<rect x="300" y="64" width="210" height="94" rx="6" fill="#0c2d6b" stroke="#58a6ff" stroke-width="2"/>
+<text x="405.0" y="96" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">Lead session</text>
+<text x="405.0" y="114" text-anchor="middle" font-size="11.5" fill="#c9d1d9">reads the tour, asks you</text>
+<text x="405.0" y="132" text-anchor="middle" font-size="11" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#c9d1d9">/cadence:lead</text>
+<text x="570" y="22" font-weight="600" font-size="13.5" fill="#e6edf3">3. The wave</text>
+<rect x="570" y="64" width="200" height="94" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="670.0" y="96" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">Fresh sessions</text>
+<text x="670.0" y="114" text-anchor="middle" font-size="11.5" fill="#8b949e">implement, then review</text>
+<text x="670.0" y="132" text-anchor="middle" font-size="11" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#8b949e">cadence orchestrate</text>
+<text x="830" y="22" font-weight="600" font-size="13.5" fill="#e6edf3">4. You</text>
+<rect x="830" y="64" width="160" height="94" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="910.0" y="96" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">Review, deliver</text>
+<text x="910.0" y="114" text-anchor="middle" font-size="11.5" fill="#8b949e">one project at a time</text>
+<text x="910.0" y="132" text-anchor="middle" font-size="11" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#8b949e">/cadence:deliver</text>
+<polyline points="240,111 298,111" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arq)"/>
+<polyline points="510,111 568,111" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arq)"/>
+<polyline points="770,111 828,111" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arq)"/>
+</svg>

package/docs/quickstart-light.svg

@@ -0,0 +1,33 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1010 190" width="1010" height="190" role="img" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif" font-size="13" fill="#1f2328">
+<title>One lead, several projects, one wave</title>
+<desc>A parent folder holds the projects alpha and beta, each with its own plan. The lead session reads their tour and you choose the lots. A wave of fresh sessions does the work, then you review and deliver.</desc>
+<defs><marker id="arq" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 z" fill="#57606a"/></marker></defs>
+<rect width="1010" height="190" fill="#ffffff"/>
+<text x="20" y="22" font-weight="600" font-size="13.5" fill="#1f2328">1. Parent folder</text>
+<rect x="20" y="32" width="220" height="140" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5" stroke-dasharray="5 4"/>
+<text x="130" y="52" text-anchor="middle" font-size="11.5" fill="#57606a">atelier/ (not a repository)</text>
+<rect x="40" y="64" width="180" height="42" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="130" y="83" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">alpha</text>
+<text x="130" y="98" text-anchor="middle" font-size="11" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#57606a">raf init · plan</text>
+<rect x="40" y="116" width="180" height="42" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="130" y="135" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">beta</text>
+<text x="130" y="150" text-anchor="middle" font-size="11" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#57606a">raf init · plan</text>
+<text x="300" y="22" font-weight="600" font-size="13.5" fill="#1f2328">2. The lead</text>
+<rect x="300" y="64" width="210" height="94" rx="6" fill="#ddf4ff" stroke="#0969da" stroke-width="2"/>
+<text x="405.0" y="96" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">Lead session</text>
+<text x="405.0" y="114" text-anchor="middle" font-size="11.5" fill="#57606a">reads the tour, asks you</text>
+<text x="405.0" y="132" text-anchor="middle" font-size="11" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#57606a">/cadence:lead</text>
+<text x="570" y="22" font-weight="600" font-size="13.5" fill="#1f2328">3. The wave</text>
+<rect x="570" y="64" width="200" height="94" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="670.0" y="96" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">Fresh sessions</text>
+<text x="670.0" y="114" text-anchor="middle" font-size="11.5" fill="#57606a">implement, then review</text>
+<text x="670.0" y="132" text-anchor="middle" font-size="11" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#57606a">cadence orchestrate</text>
+<text x="830" y="22" font-weight="600" font-size="13.5" fill="#1f2328">4. You</text>
+<rect x="830" y="64" width="160" height="94" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="910.0" y="96" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">Review, deliver</text>
+<text x="910.0" y="114" text-anchor="middle" font-size="11.5" fill="#57606a">one project at a time</text>
+<text x="910.0" y="132" text-anchor="middle" font-size="11" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#57606a">/cadence:deliver</text>
+<polyline points="240,111 298,111" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arq)"/>
+<polyline points="510,111 568,111" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arq)"/>
+<polyline points="770,111 828,111" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arq)"/>
+</svg>

package/docs/quickstart.md

@@ -0,0 +1,138 @@
+[← cadence](../README.md)
+
+# Start in 10 minutes: one lead, several projects
+
+You keep a folder with a few small projects. A **lead** session looks at all of them, you choose what to
+do, and a program runs each lot in fresh sessions. This page takes you from nothing to the first wave.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="quickstart-dark.svg">
+  <img alt="A parent folder holds the projects alpha and beta; the lead session reads their tour and you choose; a wave of fresh sessions works; you review and deliver" src="quickstart-light.svg">
+</picture>
+
+The commands below were played on a clean Windows 11 machine with WSL (Ubuntu 24.04, L357): about 40 seconds of commands,
+29 of them for Node and Claude Code. The rest of the ten minutes is reading and typing.
+
+## Before you start
+
+You need four things; the page says how to check each.
+
+- **Node 22.18 or later** (`node --version`). If you have none: [nvm](https://github.com/nvm-sh/nvm), or the NodeSource
+  package of your distribution (`setup_22.x`). Node 20 is not enough.
+- **git, with an identity.** Without one, the first `git commit` stops with `empty ident name`:
+
+  ```sh
+  git config --global user.name "Your Name"
+  git config --global user.email "you@example.com"
+  ```
+
+- **Claude Code, installed and logged in.** `claude auth status` must print `"loggedIn": true`. A wave opens
+  `claude -p` sessions and stops at the first one with `Not logged in · Please run /login` otherwise.
+  Install it from [claude.com/claude-code](https://claude.com/claude-code), then run `claude` once and log in.
+- **A test command** for each project (`npm test`, `pytest`, `go test ./...`). The wave runs it after every change.
+
+## Install
+
+```sh
+npm install -g @sylad/cadence
+cadence --version
+```
+
+If npm answers `EACCES: permission denied, mkdir '/usr/lib/node_modules/@sylad'`, your Node belongs to the system.
+Give npm a folder of your own, then install again:
+
+```sh
+npm config set prefix ~/.npm-global
+export PATH="$HOME/.npm-global/bin:$PATH"     # add this line to ~/.bashrc or ~/.zshrc too
+npm install -g @sylad/cadence
+```
+
+The skills and agents come as a Claude Code plugin:
+
+```sh
+claude plugin marketplace add Sylad/cadence
+claude plugin install cadence@cadence
+```
+
+## The parent folder
+
+The lead works from a folder that holds the projects as sub-folders. The folder itself is not a repository.
+Each project is one: give it a plan with `raf init`, a first lot, and the test command, in one commit.
+Run the block once per project (here `alpha`, then `beta`):
+
+```sh
+mkdir alpha && cd alpha
+git init -b main
+raf init
+raf add "Create hello.txt containing hello" --estimate 0.25
+cat > cadence.yaml <<'EOF'
+orchestrate:
+  test: test -f hello.txt        # passes once the first lot has created hello.txt
+EOF
+git add -A && git commit -m "chore: init raf"
+raf ignore $(git rev-parse --short HEAD)
+git add .cadence/raf.yaml && git commit -m "plan: acknowledge init"
+cd ..
+```
+
+What it does: `raf init` writes the plan (`.cadence/raf.yaml`), a commit hook and a `.gitignore` line. The commit
+that adds the plan cites no lot, so `raf` warns `commit sans lot` and `raf check` would list it as a gap: `raf ignore`
+acknowledges it once, and the plan records that. `cadence.yaml` is the project's settings file; its single
+`orchestrate.test` line is the minimum the wave needs, and without it the tour warns `porte de tests absente`.
+The folder is empty, so the gate here is `test -f hello.txt`, which the toy lot satisfies. On a project that already exists,
+put its own test command there (`npm test`, `pytest`, `go test ./...`): `npm test` in a folder without `package.json` fails.
+The reference for every other key is [orchestrate](orchestrate.md) and [deliver](deliver.md).
+
+Then, from the parent folder:
+
+```sh
+cadence lead tour
+```
+
+It prints one line per project: lots in progress, drift, next lot, repository state. Expect `alpha · en cours rien ·
+dérive aucune · … · prochain L1 Create hello.txt containing hello · dépôt propre`, and the same for `beta`. This is the table the lead reads.
+
+## Start the lead
+
+Open Claude Code in the parent folder and call the skill:
+
+```sh
+claude
+```
+
+then type `/cadence:lead` (or say « pilot all projects »). The lead runs the tour, reports in a table, proposes three
+lots and **waits for your priority**: nothing starts before you answer. [The lead workflow](lead.md) draws every step.
+
+## The first wave
+
+When you pick `alpha:L1`, the lead launches a wave. You can do it yourself, from the parent folder:
+
+```sh
+cadence orchestrate alpha:L1 --dry-run
+cadence orchestrate alpha:L1 --wave first
+```
+
+The first line only prints what would run: each step, its model and its budget. The second runs the lot in fresh
+sessions: implement, then review, and hands the lot back to you. From inside a project, write `.:L1` instead of
+`alpha:L1` (the project is a sub-folder of the current folder, so `alpha:L1` from inside `alpha` finds nothing).
+
+The sessions of a wave never push and never deliver. You read the table, answer the questions it brings back, then
+`/cadence:deliver` ships one project at a time ([deliver](deliver.md)). How waves, budgets and reviews work: [orchestrate](orchestrate.md).
+
+## If it stops
+
+| You see | Cause | Do |
+|---|---|---|
+| `npm: command not found` | no Node | install Node 22.18+ (above) |
+| `EACCES: permission denied, mkdir '/usr/lib/node_modules/@sylad'` | system-owned Node | `npm config set prefix ~/.npm-global` (above) |
+| `fatal: empty ident name … not allowed` | no git identity | the two `git config --global` lines (above) |
+| `Not logged in · Please run /login` | Claude Code not logged in | `claude`, log in, then `claude auth status` |
+| `porte de tests absente` | no `orchestrate.test` | the `cadence.yaml` line of the project block |
+| `alpha:L1 … introuvable` | launched from inside `alpha` | use `.:L1` |
+
+A problem that is not here: [open an issue](https://github.com/Sylad/cadence/issues/new/choose) with `cadence --version` and the command you ran.
+
+## Not played
+
+The lead skill and a wave played to the end (review, `raf done`, delivery) were not played on that machine, which was not logged
+in to Claude Code; the tour, the dry run and the dry delivery were. Other systems (macOS, native Linux, PowerShell without WSL) were not played either.

package/docs/raf.md

@@ -55,7 +55,7 @@ raf gantt                         # .cadence/gantt.html (next to the plan)
 | `raf spec <id> on\|off` | set or remove `spec:` on an existing lot (a lot that changes a behaviour, for the back-end spec step of `cadence orchestrate`, see [The spec step of a lot with `spec: true`](orchestrate.md#the-spec-step-of-a-lot-with-spec-true)); refused on a sub-task; `off` is refused on a lot that has `screen: page` (the page implies the spec: remove `screen:` first) and `on` there only says so and changes nothing; on `component` and `journey` (ordinary path since L209) both work and set or remove the back-end `spec:`. `raf spec` only takes `on`/`off`: `cadence spec check\|qa <fiche.yaml>` keeps its own subcommands. `raf check` reports a `spec:` that is neither `true` nor `false` (`spec : true ou false attendu`) |
 | `raf uses <lot> [<resource>…]` | replace the `uses:` list of a lot of any status (`done` and `dropped` included) by the names given (duplicates removed, order kept); with no name, remove the key. Prints nothing. A name is a word of lowercase letters, digits, `-` and `_` (else `ressource invalide : <name> (lettres minuscules, chiffres, - et _)`, plan unchanged); a sub-task is refused (`uses se pose sur un lot, pas sur une sous-tâche : L1/t1`); an unknown lot is `lot inconnu : <id>`. A name not yet declared is accepted: `raf check` refuses it (L251) |
 | `raf public <id> "title"` · `raf public <id> --clear` | set, replace or remove the public title of a lot |
-| `raf start <id>` · `raf done <id> [--force]` · `raf drop <id> [--reason text]` | dated transitions (`done` refuses open sub-tasks unless `--force`, and a lot whose `acceptation-<lot>.json` is still `vert: false`, L366: closed like that it would lock every later wave of the repository, see `cadence spec green`; with `--force` it only warns on stderr) |
+| `raf start <id>` · `raf done <id> [--force]` · `raf drop <id> [--reason text]` | dated transitions (`done` refuses open sub-tasks unless `--force`, and a lot whose `acceptation-<lot>.json` is still `vert: false`, L366: closed like that it would lock every later wave of the repository, see `cadence spec green`; with `--force` it only warns on stderr. Like every `raf` command it only writes the plan file and **never commits** it: when the plan or a file `plan.onWrite` produces is left with changes, `done` prints the `git add` / `git commit` command that takes them, the subject from the `plan.commit` template, L371) |
 | `cadence spec green <lot>` | L366: run the dedicated acceptance command (`orchestrate.accept`) on a lot driven or closed by hand; green, set `vert: true` in its `acceptation-<lot>.json` and commit that file alone (subject `chore(<lot>): acceptation verte, vert: true posé par cadence spec green` or the `plan.commit` template; the resealed tests are listed in the commit body, never in the subject), resealing the fingerprints of the listed tests refined since the red commit (journal `resceaux`) so the lock goes quiet; a listed test changed but not committed is refused. Red: exit 1, nothing changed. Refused for a `todo` lot, during a wave, and while an unfinished wave keeps a lot of the repository open; see [orchestrate](orchestrate.md) |
 | `raf todo <id> [--reason text]` | put a started lot back to `todo` (`doing` → `todo`, `started:` removed, dated note « remis en attente : reason »): refused when work commits cite the lot (plan-only and version commits do not count, as `raf commits`), when the lot is not `doing` (a `done` or `dropped` lot is reopened by hand), or on a sub-task; sub-tasks and other keys are left as they are |
 | `raf migrate [--dry-run]` | move `docs/plan/raf.yaml` to `.cadence/raf.yaml` and rewrite the readers of the old path in the repository, see [Moving the plan: `raf migrate`](#moving-the-plan-raf-migrate) |
@@ -66,7 +66,7 @@ raf gantt                         # .cadence/gantt.html (next to the plan)
 | `raf now` | what to do next |
 | `raf list [--status s]` | flat list |
 | `raf docs-ok <lot> --reason text` | acknowledge the `docs.sync` gap of a lot (a document behind its commits, `raf check` red) when the documentation really stays true: a `docs_ok: { date, reason }` key on the lot, **the reason is required** (refused without it, for an unknown lot or for a sub-task); `raf check` and `cadence lead tour` no longer count the lot, `raf show` prints it, and `cadence orchestrate` neither calls the librarian nor holds the lot back for it. Commit the plan with it |
-| `raf ignore <sha> \| "exact subject" [--reason text]` | acknowledge a commit without a lot (tooling chore, a plan commit citing an unknown id) without rewriting history: a dated, reasoned line in the plan's `acknowledged:` section; a sha is exact, a subject covers every commit carrying it; exactly one commit argument, the reason goes through `--reason "text"` (`raf ignore 1a2b3c4 "tooling"` is refused with « un seul commit attendu ; la raison se passe par --reason "texte" », exit 2) |
+| `raf ignore <sha> \| "exact subject" [--reason text]` | acknowledge a commit without a lot (tooling chore, a plan commit citing an unknown id) or a commit that cites known lots without working on them (a lead's plan commit creating lots, a setting cited in parentheses): it then counts for none of them — not started, not active, not to review (`raf commits` omits it) — without rewriting history: a dated, reasoned line in the plan's `acknowledged:` section; a sha is exact, a subject covers every commit carrying it; exactly one commit argument, the reason goes through `--reason "text"` (`raf ignore 1a2b3c4 "tooling"` is refused with « un seul commit attendu ; la raison se passe par --reason "texte" », exit 2) |
 | `raf check --ignored` | list the acknowledged commits with their date and reason |
 | `raf check [--since date] [--idle 7]` | since the plan's adoption date by default (a visible lot without a public title is only a `⚠` warning: it never changes the exit code): commits without a lot (commits touching only plan files, or only version fields, `CHANGELOG.md`, the README's « What's new » section and `docs/whats-new.md` are exempt), unknown ids, `todo` lots that already have commits, idle lots (an open lot whose sub-lots, entries carrying `parent:` in a plan kept by another tool, have a recent commit or are in progress is not idle: L321), `done` lots with open sub-tasks, bad or circular dependencies, and an open lot titled « Revue UX — <screen> » without `visible: true` (`ux-review-not-visible`, an error: such a lot goes through precheck → implement → review with no UX step, so the screen is never reviewed — finance L32 on 2026-10-23; L271; the message names the fix, `raf visible <id> on`, L273; on a read-only plan, plan kept by another tool, it never names a `raf` command, which would refuse: with `plan.fields.visible` mapped it says to set `visible:` with the project's tool, without it it says the plan carries no `visible`, to map the field in `cadence.yaml` (`plan.fields.visible`) if the project's tool writes it, and that otherwise the UX review of that screen happens outside orchestrate, L321) |
 | `raf gantt [-o file]` | standalone Gantt page |
@@ -155,6 +155,7 @@ plan:
   commit: 'chore({lot}): {action} (orchestrate {vague})'
 ```
 
+- `raf done <lot>` does not commit the plan (it never does, see below) but prints the command that would, with this template: `{action}` is `terminé` and, outside a wave, the group holding `{vague}` is dropped (`chore(L12): terminé`). Without a template: `plan: L12 terminé`.
 - `{lot}` is required (a commit must cite its lot); `{action}` is what was done (`démarré`, `revue de code enregistrée`, `revue de code notée`, `hypothèses de la fiche <sujet> notées`, `mineurs de la revue de <revue> notés`, `règles R1, R2 sourcées par la réponse du lead`, `test d'acceptation rescellé (<test>)`);
   `{vague}` is the wave id. A word between braces that is none of these, an empty template or one on several lines is refused when the config is read.
 - Outside a wave (`spec reseal`) there is no wave: the parenthesised group that holds `{vague}` is dropped, so the template above gives `chore(L17): test d'acceptation rescellé (…)`.

package/docs/whats-new.md

@@ -4,6 +4,8 @@
 
 ## In two lines
 
+- **1.15.1**: a getting-started page (`docs/quickstart.md`) takes a lead of several projects from install to the first wave and lists the usual stops; GitHub issue templates for bugs and requests; a contrast fix in the dark figure.
+- **1.15.0**: worktree integration settles the `CHANGELOG.md` conflict by itself; `--integrate` accepts a lot corrected and reviewed outside the wave; `raf ignore` clears a plan commit citing lots; `raf done` gives the plan commit.
 - **1.14.1**: publishes 1.14.0 (tagged, never published): Node 22.18 or later is required; `plan.commit`, `plan.onWrite`, `orchestrate.testReplay`, `spec green`, `ref coverage` and `verify --gate --sha`.
 - **1.14.0**: Node 22.18 or later is now required (Node 20 dropped). `plan.commit`, `plan.onWrite` and `orchestrate.testReplay` fit a wave to your hooks, files and load; `spec green`, `ref coverage` and `verify --gate --sha` are new.
 - **1.13.0**: `cadence release` prepares the version commit; `cadence config set --all` sets one key in every project; waves share the machine between sessions, reserve a budget for the escalation and tolerate the lead's delivery push.
@@ -35,6 +37,10 @@ Each is a paragraph in [docs/whats-new.md](whats-new.md) and a full section in [
 
 The long form of « In two lines » above (the README no longer carries a « What's new » section since L326: it links here). The full history, with the date of each version, is in [CHANGELOG.md](../CHANGELOG.md).
 
+**1.15.1**: a way in for a lead who has never used cadence. A new getting-started page, `docs/quickstart.md` (L358, a section of the README), goes from install to the first wave: the parent folder, `raf init` in each project with the minimal `cadence.yaml`, the tour, `/cadence:lead`, the first wave, and a table of the usual stops (no Node, `EACCES`, no git identity, Claude Code not logged in). It comes from a walkthrough measured on a clean machine. Two GitHub issue templates, bug and request, are forms (L358, `.github/ISSUE_TEMPLATE/`); a `config.yml` turns off blank issues and points to the getting-started page, and the bug form asks for `cadence --version`, the steps and what was printed. The dark getting-started figure (`docs/quickstart-dark.svg`) draws the grey texts of « Lead session » in a lighter grey, 4.26:1 on the blue before and now above the 4.5:1 of WCAG 2.2 AA, and `docs/overview.md` lists `docs/quickstart.md` in its map of the pages (L374).
+
+**1.15.0**: fewer lots handed back, and fewer manual detours, on the lead's side. The integration of `cadence orchestrate` in worktree mode no longer hands a lot back for a `CHANGELOG.md` conflict when the branch was released while the lot lived (L369, `docs/orchestrate.md`): an entry that the release moved under the published version is no longer read as a removal, and the entries a lot's commits wrote then reworded are dropped in favour of the version at the tip of the lot's branch, so one final entry per lot is left. `cadence orchestrate --resume --integrate <project:lot>` now accepts a lot handed back for its budget or a non-compliant review that the lead corrected and reviewed outside the wave (L370, `docs/orchestrate.md`, `docs/lead.md`): fix in the worktree, `raf review` there with the plan committed there, then `--integrate`; the lot restarts at the integration step with that verdict instead of the refusal « le lot n'est pas rendu à l'étape d'intégration ». A review older than a commit of the lot, or none, keeps the refusal. If the lead also wrote on that lot in the repository's plan meanwhile, the plan conflict of the rebase is settled by the program, provided that plan commit adds nothing but lot reviews. `raf ignore` also acknowledges a commit that cites known lots (L372): a plan commit that creates lots or cites a setting in parentheses was counted as work on those lots and could not be cleared; an acknowledged commit now counts for no lot, `raf commits` no longer lists it, and `raf check --ignored` does. `raf done <lot>` says that it did not commit the plan (L371): it never has, `raf` only writes the plan file, so when the plan or a file `plan.onWrite` produces has changes, the message prints the `git add` and `git commit` that take them, the subject following the project's `plan.commit` template.
+
 **1.14.1**: 1.14.0 was tagged but never published (a test of the Node minimum read only `[Unreleased]`, which the version commit empties, a fault of the test and not of the tool, L368); 1.14.1 publishes it as it stands, so everything listed under 1.14.0 below arrives with it, Node 22.18 or later first.
 
 **1.14.0**: **Node 22.18 or later is now required (Node 20 dropped)** (L365, `docs/stabilite.md`, `docs/releasing.md`): `engines.node` goes from `>=20` to `>=22.18`, the first release that runs `.ts` files without a tool, which the test suite depends on, and Node 20 is out of maintenance; it ships in a minor version because the minimum Node version now follows the maintained LTS lines. Upgrade Node before installing it. A wave fits the project it runs in. `plan.commit` in `cadence.yaml` (L343) is a template (`{lot}`, `{action}`, `{vague}`) for the subject of every plan commit, so a `commit-msg` hook that enforces Conventional Commits no longer fails a lot before any session, and `--dry-run` plays each subject through the repository's real hook. `plan.onWrite: { command, files }` (L346) regenerates the files derived from the plan after every write and commits them with it; a failing command refuses the write. Models are free (L345): `@<model>` of a lot and `orchestrate.review.light` / `full` take any name `claude --model` accepts. The gate runs under the project's Node, the `.nvmrc` first (L351). Fewer lots lost for nothing. `orchestrate.testReplay` (L354, `docs/orchestrate.md`) replays a red test of the gate alone before it counts, so a test that fails only under load is reported as unstable instead of triggering correction passes; a lot whose gate is green is no longer corrected (L361); the integration rebases again, up to twice, when the branch moved meanwhile (L364), and files the entries under the right `[Unreleased]` (L362). For the lead. `cadence spec green <lot>` and a refusal of `raf done` on a lot whose acceptance is still red (L366) stop a lot closed by hand from locking the tests of every later wave. `cadence ref coverage <inventaire.json>` and the `reference-planner` agent (L367) list the elements of a reference document that no lot covers. `cadence verify --gate --sha <sha>` (L348) replays the gate at a commit in a throwaway worktree. `lead tour` and `session` flag a close note that quotes a lot already done (L347). `cadence release` now prints the whole plugin update (L359), the test suite no longer depends on `TMPDIR` (L360), and the measured walk of a new user (L357) is in `docs/mesures/`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sylad/cadence",
-  "version": "1.14.1",
+  "version": "1.15.1",
   "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",
@@ -44,6 +44,9 @@
     "docs/fonctionnement-lead-dark.svg",
     "docs/lead-workflow-light.svg",
     "docs/lead-workflow-dark.svg",
+    "docs/quickstart.md",
+    "docs/quickstart-light.svg",
+    "docs/quickstart-dark.svg",
     "docs/cycle-vague-light.svg",
     "docs/cycle-vague-dark.svg",
     "LICENSE"

package/skills/lead/SKILL.md

@@ -107,7 +107,7 @@ handed back too. `cadence orchestrate --stop-after-current` lets the sessions ru
 ends `interrupted`, and `--resume --wave <wave>` takes it up again (the command printed names the wave). To take a lot out of a wave that is already stopped, use
 `--resume --wave <wave> --drop <project>:<lot>` (the lot is handed back instead of being replayed). Neither kills a session.
 
-**One worktree per lot** (`orchestrate.worktrees`, L279) is on by default in cadence's own `cadence.yaml` since 2026-10-25 (L320) and off in a project that does not set the key (the key is the whole switch: no environment variable). Two independent lots of one repository then play at once, each in its own worktree, and the program integrates them. Its options belong to that mode: `--resume --wave <wave> --integrate <project:lot>` replays a lot handed back at the integration step (the wave's output names that exact command), `--replay <project:lot>` also after a refused plan write, `--remove-worktree <project:lot> [--abandon-commits]` removes a kept worktree and branch, and `cadence orchestrate --status` and `cadence lead tour` list the worktrees kept by waves (nothing to list in the default mode).
+**One worktree per lot** (`orchestrate.worktrees`, L279) is on by default in cadence's own `cadence.yaml` since 2026-10-25 (L320) and off in a project that does not set the key (the key is the whole switch: no environment variable). Two independent lots of one repository then play at once, each in its own worktree, and the program integrates them. Its options belong to that mode: `--resume --wave <wave> --integrate <project:lot>` replays a lot handed back at the integration step (the wave's output names that exact command) and, since L370, a lot handed back for its budget or a non-compliant review that you had corrected and reviewed outside the wave (the gesture is under « A lot handed back despite the escalation », section 3), `--replay <project:lot>` also after a refused plan write, `--remove-worktree <project:lot> [--abandon-commits]` removes a kept worktree and branch, and `cadence orchestrate --status` and `cadence lead tour` list the worktrees kept by waves (nothing to list in the default mode).
 
 **Delivering while the wave runs.** A lot that turns **ready** in the journal is not left waiting: once the lead has re-verified it (section 3, point 2) and recorded its verdict (`raf done`), it delivers that lot at once, without waiting for the end of the wave. The re-check runs at that sha with `cadence verify --gate --sha <sha>` (a throwaway worktree whose untracked dependencies are linked from the main tree, removed afterwards), never in the shared tree, which holds the lots still running. Take the sha to deliver from `git log`: the last commit of the ready lot such that no commit of a lot that is not ready (running, queued, in question, handed back) sits beneath it — the same « livrable jusqu'à » the final table prints. Push that sha alone (`git push origin <sha>:main`, never HEAD, which holds the code of lots still running; the wave tolerates exactly this push — the journal says « push du lead (livraison de <lot>) toléré » — because the sha is an ancestor of HEAD holding no commit of a lot of the wave that is not ready (a commit that cites no lot passes), whereas any other push still stops the wave as an incident), then `cadence deliver --dry-run --sha <sha>` and `cadence deliver --sha <sha>`: `deliver` accepts a `--sha` during a wave of the same repository when none of its commits belongs to a lot that is not ready, and refuses otherwise, naming the lots. Without `--sha` it stays refused until every lot of the repository is ready or handed back. The wave's sessions keep committing in the working tree: `--sha` never reads it. What the log keeps is `<sha>`, unless the delivery script declares another deployed commit in `CADENCE_DEPLOYED_FILE`; if HEAD moved during the delivery without that declaration, `deliver` warns (« la tête a avancé pendant la livraison ») and the log keeps `<sha>`: it is not a failure. This is the measured gain: a ready lot used to wait for the slowest lot of its wave (1,554 lot-minutes between « ready » and the end of the wave over 28 waves).
 
@@ -141,7 +141,7 @@ of the plan itself (section 2b), and the limits of section « Limits that always
 handed back ready (refused, review not compliant after the correction passes, red delivery, blocking QA finding) is
 not chained over: it is reported, and the chain goes on with the lots that do not depend on it.
 
-**A lot handed back despite the escalation** (L337). When the project declares `orchestrate.escalation: { model }`, the wave itself plays one correction and one fresh review on that model before handing a lot back for a non-compliant review or red tests: do not take such a lot up by hand on a model of your own choice first, and do not replay the escalation yourself. The table says `escalade <model> : …` under the lot. A lot handed back **despite** the escalation (`rendu malgré l'escalade`) is for the human or for an arbitration (the sheet, the brief or the lot is at fault, not the model): report it with the remaining findings and go on with the other lots. `escalade … non jouée` means the lot's budget did not cover it: the lot is yours, with its findings. `escalade … session escaladée sans résultat` means the escalated session itself failed (often a model the account does not have): the model never judged the lot, fix the key or take the lot up, do not read it as the lot's fault. A line `en cours` is a lot still running; `engagée, lot rendu avant le verdict du modèle` is a lot withdrawn, failed by an error or stopped by an incident during the escalation: the model did not judge it, read the lot line for the reason. Without the key, nothing changes; the model has no default, as the account may not have the strongest one.
+**A lot handed back despite the escalation** (L337). When the project declares `orchestrate.escalation: { model }`, the wave itself plays one correction and one fresh review on that model before handing a lot back for a non-compliant review or red tests: do not take such a lot up by hand on a model of your own choice first, and do not replay the escalation yourself. The table says `escalade <model> : …` under the lot. A lot handed back **despite** the escalation (`rendu malgré l'escalade`) is for the human or for an arbitration (the sheet, the brief or the lot is at fault, not the model): report it with the remaining findings and go on with the other lots. `escalade … non jouée` means the lot's budget did not cover it: the lot is yours, with its findings. **Taking such a lot up** (handed back for its budget or a non-compliant review, L370): fix it in its kept worktree (the final table gives the path; a fix subagent there, under `cadence lead hold`), then run `raf review <lot> "conforme : …"` **in that worktree** and commit its plan there — the review is read from the worktree's plan, not from the main repository's, and it must come after the last work commit of the lot —, then `cadence orchestrate --resume --wave <wave> --integrate <project>:<lot>`: the program rebases, replays the checks, keeps your verdict (or makes a short review of the rebased diff) and advances the repository's branch. Do not integrate it by hand any more (L367, 26-10), and do not record that review in the main repository's plan: `--integrate` would not see it and would keep refusing (« pas rendu à l'étape d'intégration »). `escalade … session escaladée sans résultat` means the escalated session itself failed (often a model the account does not have): the model never judged the lot, fix the key or take the lot up, do not read it as the lot's fault. A line `en cours` is a lot still running; `engagée, lot rendu avant le verdict du modèle` is a lot withdrawn, failed by an error or stopped by an incident during the escalation: the model did not judge it, read the lot line for the reason. Without the key, nothing changes; the model has no default, as the account may not have the strongest one.
 
 **The threshold.** Before every new wave, read the context of the lead session with `cadence session context`: the
 `cadence-hud` mod publishes the context of each session, one file per session named after its id, and the command reads the