@sylad/cadence 1.13.0 → 1.15.0

package/dist/orchestrate/integrate.js

@@ -1,17 +1,21 @@
 import { execFileSync } from 'node:child_process';
-import { writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { gitCommonDir } from '../git.js';
 import { sharedStateDir } from '../state.js';
 import { activeLock, releaseLock, takeLock } from './lock.js';
-import { mergeUnreleased } 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';
 /** Attente du verrou d'intégration (R25) : une intégration dure un rebase et la relance des tests. */
 export const INTEGRATE_WAIT_MS = 10 * 60_000;
 export const INTEGRATE_POLL_MS = 1_000;
+/** Rebases rejoués quand la branche du dépôt avance pendant l'intégration (L364) : au-delà, le lot est rendu. */
+export const MAX_REPLAYS = 2;
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 /**
  * Prend la main sur le dépôt pour une intégration ou une écriture de plan du programme (R10, R21, R26) : d'abord la file en mémoire du dépôt (les lots d'une
@@ -77,9 +81,93 @@ 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.
+ */
+function moveOwnEntries(work, base, before, start) {
+    if (start === undefined)
+        return 0;
+    const [tip, main] = [tryGit(work, 'show', `${before}:${CHANGELOG}`), tryGit(work, 'show', `refs/heads/${base}:${CHANGELOG}`)];
+    if (tip === null || main === null || !existsSync(join(work, CHANGELOG)))
+        return 0;
+    const fixed = moveToUnreleased(readFileSync(join(work, CHANGELOG), 'utf8'), tip, start, main);
+    if (!fixed)
+        return 0;
+    writeFileSync(join(work, CHANGELOG), fixed.text);
+    run(work, 'add', '--', CHANGELOG);
+    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.
  */
@@ -96,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) };
@@ -111,7 +199,9 @@ export function rebaseOnto(work, base) {
             }
         }
     }
-    return { kind: 'rebased', before, after: git(work, 'rev-parse', 'HEAD'), changelog };
+    const moved = moveOwnEntries(work, base, before, start);
+    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
@@ -127,3 +217,5 @@ export function patchId(cwd, from, to) {
 export function advance(repo, branch) {
     git(repo, 'merge', '--ff-only', '--quiet', `refs/heads/${branch}`);
 }
+/** Vrai quand la branche du dépôt n'est plus un ancêtre de celle du lot : elle a avancé depuis le rebase, l'avance rapide est impossible (L364). */
+export const baseMoved = (repo, branch, base) => tryGit(repo, 'merge-base', '--is-ancestor', `refs/heads/${base}`, `refs/heads/${branch}`) === null;

package/dist/orchestrate/launch.js

@@ -9,6 +9,8 @@ import { SlotAbandoned } from './registry.js';
 import { TEST_WORKERS_ENV } from './workers.js';
 import { killMarked, SESSION_MARK_VAR, TreeTracker } from '../proc.js';
 import { isQuotaMessage, lacksStructuredOutput, parseSession, salvageUsage, sumTokens, tokensOf } from './result.js';
+/** Les alias que `claude --model` comprend sans connaître le compte : tout autre nom est passé tel quel (L345) et le dry-run en avertit. */
+export const MODEL_ALIASES = ['haiku', 'sonnet', 'opus'];
 /**
  * Serveurs MCP d'une étape : Playwright pour `ux` et `maquette` (revue des captures et du HTML local, L172) et, sur un lot `visible`, pour `spec` quand il a un écran `screen:` (rendu 1440/390 de la maquette, L171), `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.

package/dist/orchestrate/state.js

@@ -8,7 +8,7 @@ import { gitCommonDir, gitRoot } from '../git.js';
 export const LOCAL_PRECHECK_UNREADABLE = 'contrôle préalable : rapport du modèle local illisible';
 export const PRECHECK_UNREADABLE = 'contrôle préalable illisible, implémentation lancée';
 export function newLot(o) {
-    return { ...o, status: 'queued', pass: 0, next: null, steps: [], constats: [], verdict: null, uxVerdict: null, questions: [], choix: [], answers: [], proposals: [], warnings: [], outcome: null };
+    return { ...o, status: 'queued', pass: 0, next: null, steps: [], constats: [], verdict: null, uxVerdict: null, questions: [], choix: [], answers: [], proposals: [], warnings: [], instables: undefined, outcome: null };
 }
 /** Un lot fini ne travaille plus dans son dépôt : prêt, rendu ou échoué. */
 export const lotFinished = (l) => l.status === 'ready' || l.status === 'handed-back' || l.status === 'failed';

package/dist/orchestrate/workers.js

@@ -1,4 +1,5 @@
 // Part de la machine de chaque session (L350) : le 26-10, 32 cœurs et 4 sessions, vitest à 31 workers par suite, et des tests qui passaient seuls rougissaient ensemble.
+import { stripAnsi } from './baseline.js';
 /** Variable posée dans l'environnement des sessions et de la porte : le nombre de workers que leurs lanceurs de tests ont le droit d'ouvrir. */
 export const TEST_WORKERS_ENV = 'CADENCE_TEST_WORKERS';
 /** Cœurs ÷ plafond de sessions, arrondi vers le bas, jamais moins de 1 (cœurs inconnus ou plafond absurde compris). */
@@ -18,3 +19,53 @@ export function testWorkersFrom(env, cores, cap) {
 export function testWorkersText(n) {
     return `Machine share: the program splits the machine between the sessions of the wave, and yours gets \`${TEST_WORKERS_ENV}=${n}\` (cores ÷ session cap, in your environment and in the program's test gate). Every test runner you launch respects it: \`vitest run --minWorkers=1 --maxWorkers=$${TEST_WORKERS_ENV}\` (vitest 2 refuses \`--maxWorkers\` alone: its default minimum is the core count), \`jest --maxWorkers=$${TEST_WORKERS_ENV}\`, \`pytest -n $${TEST_WORKERS_ENV}\` (pytest-xdist), and the same option of any other runner; never the default (all the cores of the machine for each session at once: tests that pass alone then fail together, on timeouts). A test that fails in the whole suite and passes when run alone is a load failure, not a defect to fix.`;
 }
+/**
+ * Le fichier à rejouer seul pour un test rouge : « fichier > suite > test » (vitest), « fichier::test » (pytest), « fichier » seul (jest : `FAIL src/a.test.ts`).
+ * En espace de travail le nom est précédé de « |paquet| » : ce n'est pas une partie du chemin. Null quand le nom n'en désigne aucun (rien à rejouer seul) : y compris le « Suite › test » de jest, que `jestTestFiles` rattache au fichier FAIL qui le précède dans la même sortie.
+ */
+export function replayFile(test) {
+    // Le premier séparateur rencontré borne le chemin : un « :: » ou un « > » dans le titre du test (« a.test.ts > suite > cas::x ») n'en fait pas partie.
+    const seps = [test.indexOf('::'), test.indexOf(' > ')].filter((i) => i >= 0);
+    const head = seps.length ? test.slice(0, Math.min(...seps)) : /^\S+$/.test(test.trim()) ? test : '';
+    const file = head.trim().replace(/^\|[^|\s]*\|\s+/, ''); // espace de travail vitest : « |paquet|  src/a.test.ts »
+    return /^\S.*\.\w+$/.test(file) ? file : null;
+}
+/** Un argument de commande sans risque pour `sh -c` : tel quel s'il est simple, entre apostrophes sinon. */
+export function shellArg(s) {
+    return /^[\w./@+=,:-]+$/.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * Une porte composée : plusieurs lanceurs ou un sous-shell, c'est-à-dire un `&&` ou un `||` hors apostrophes et guillemets, ou une parenthèse (sous-shell `( … )`, substitution `$( … )`, fonction). Le premier lanceur qui rougit coupe avant le suivant :
+ * le rejeu seul d'un de ses tests ne dit rien du reste. `orchestrate.testReplay` est refusé à la lecture de cadence.yaml pour une telle porte (L354) : le rejeu seul ne vaut que pour un lanceur unique.
+ */
+export function isComposedGate(command) {
+    let quote = '';
+    for (let i = 0; i < command.length; i++) {
+        const ch = command[i];
+        if (quote) {
+            if (ch === '\\' && quote === '"')
+                i++;
+            else if (ch === quote)
+                quote = '';
+        }
+        else if (ch === '\\')
+            i++;
+        else if (ch === "'" || ch === '"')
+            quote = ch;
+        else if (ch === '(' || command.startsWith('&&', i) || command.startsWith('||', i))
+            return true;
+    }
+    return false;
+}
+/** Une ligne d'écho de la commande par son lanceur de paquets, qui recopie ses arguments (les fichiers rejoués compris) : npm 12 « npm notice run … », « npm warn … », « npm ERR! … » ; npm et pnpm « > vitest run … » ; yarn « $ vitest run … ». */
+const LAUNCHER_ECHO = /^\s*(?:npm (?:notice|warn|WARN|ERR!?|error)\b|>\s|\$\s)/;
+/**
+ * Le rejeu a-t-il exécuté ce fichier (L354) ? Il figure, chemin entier, sur une ligne du lanceur : ni une fin d'un autre chemin (`a.test.ts` dans `src/a.test.ts`), ni une ligne d'écho de la commande par npm, pnpm ou yarn, qui recopie
+ * tous les fichiers demandés, ceux qu'un lanceur d'un autre espace de travail n'a pas joués compris. Mesuré le 26-10 : npm 12.2.0 écrit « npm notice run 'vitest' run … <fichiers> » sur stderr pour `npx …` comme pour `npm test -- …`.
+ */
+export function replayRanFile(output, file) {
+    const re = new RegExp(`(?:^|[^\\w./-])${file.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?![\\w.-])`);
+    return stripAnsi(output)
+        .split('\n')
+        .some((line) => !LAUNCHER_ECHO.test(line) && re.test(line));
+}

package/dist/orchestrate/worktree.js

@@ -123,9 +123,20 @@ export function mirrorNodeModules(repo, dir, name, links) {
  * fichier ignoré le plus haut ; son parent doit exister dans le worktree (sinon rien où le relier). Rend les liens créés.
  */
 export function linkIgnored(repo, dir) {
-    const links = [];
     const ignored = git(repo, 'ls-files', '--others', '--ignored', '--exclude-standard', '--directory').split('\n').map((f) => f.replace(/\/$/, '')).filter((f) => f && !f.startsWith('.cadence') && !f.split('/').some((p) => OUTPUT_DIRS.has(p)));
-    for (const name of ignored) {
+    return linkNames(repo, dir, ignored);
+}
+/**
+ * Relie dans le worktree `dir` les dépendances que le dépôt vivant déclare (`orchestrate.worktreeDeps`, L348), par leur chemin relatif. Celles qui n'existent pas
+ * dans le dépôt vivant ne sont pas liées et sont rendues dans `missing`. Rend aussi les liens créés.
+ */
+export function linkDeclared(repo, dir, names) {
+    const present = names.filter((n) => lstatSync(join(repo, n), { throwIfNoEntry: false }));
+    return { links: linkNames(repo, dir, present), missing: names.filter((n) => !present.includes(n)) };
+}
+function linkNames(repo, dir, names) {
+    const links = [];
+    for (const name of names) {
         const to = join(dir, name);
         if (existsSync(to) || !existsSync(dirname(to)))
             continue;
@@ -224,10 +235,10 @@ export function recoverTree(repo, branch, dir, base, planFiles = new Set()) {
     }
     return { from: found.branch, unintegrated: found.unintegrated };
 }
-/** Les fichiers du plan qu'une session ne doit pas toucher, relatifs au dépôt : le fichier de plan, la page Gantt et ce qui est généré avec (`plan.files`). */
+/** Les fichiers du plan qu'une session ne doit pas toucher, relatifs au dépôt : le fichier de plan, la page Gantt et ce qui est généré avec (`plan.files`, les fichiers de `plan.onWrite`). */
 export function planFileSet(plan, repo) {
     const rel = relative(repo, plan.path);
-    return new Set([rel, join(dirname(rel), 'gantt.html'), ...plan.files]);
+    return new Set([rel, join(dirname(rel), 'gantt.html'), ...plan.files, ...plan.produced]);
 }
 /** Les commits de la branche du lot déjà dans la branche du dépôt ? */
 export function integrated(repo, branch, base) {

package/dist/perf.js

@@ -417,7 +417,7 @@ export function computePerf(input) {
         redDeliveries: mk(reds, deliveriesOf, 'up', 'throughput.delivered'),
         qaBlocking: mk(both(windows, blockingOf), both(windows, deliveredCount), 'up', twinEscaped, escapedNote),
     };
-    const result = { since: input.since ?? null, today, windows, throughput, corrections: correctionsInd, interventions, precheck, escalations: both(windows, (w) => escalationCounts(rendered(w))), tokens, delays, durations, cost, quality, orphans, warnings: [] };
+    const result = { since: input.since ?? null, today, windows, throughput, corrections: correctionsInd, interventions, precheck, escalations: both(windows, (w) => escalationCounts(rendered(w))), instables: both(windows, (w) => instableCounts(rendered(w))), tokens, delays, durations, cost, quality, orphans, warnings: [] };
     const bottleneck = bottleneckOf(causes.current);
     for (const [key, ind] of indicatorLines(result))
         if (ind.warn)
@@ -432,6 +432,11 @@ function escalationCounts(set) {
     const by = (issue) => escalated.filter((d) => d.j.escalation.issue === issue).length;
     return { lots: escalated.length, conforme: by('conforme'), rendu: by('rendu'), nonJouee: by('non jouée'), echec: by('échec') };
 }
+/** Les tests instables sous charge des lots donnés (L354). */
+function instableCounts(set) {
+    const withTests = set.filter((d) => (d.j.instables?.length ?? 0) > 0);
+    return { lots: withTests.length, tests: withTests.reduce((n, d) => n + d.j.instables.length, 0) };
+}
 const minutesOf = (s) => {
     const from = Date.parse(s.started ?? '');
     const to = Date.parse(s.ended ?? '');
@@ -653,6 +658,9 @@ export function renderPerf(r) {
     const e = r.escalations.current;
     if (e.lots > 0)
         out.push('', 'Escalade de modèle', `  escalades de modèle : ${plural(e.lots, 'lot', 'lots')} · ${e.conforme} conforme · ${e.rendu} rendu malgré l'escalade · ${e.nonJouee} non jouée · ${e.echec} en échec`);
+    const ins = r.instables.current;
+    if (ins.lots > 0)
+        out.push('', 'Porte de tests sous charge', `  tests instables sous charge : ${plural(ins.tests, 'test', 'tests')} dans ${plural(ins.lots, 'lot', 'lots')} (rouges dans la suite, verts rejoués seuls ; précédente ${r.instables.previous.tests})`);
     out.push('', 'Tokens, délais et durées (médianes par lot ou par étape)');
     for (const l of lines.slice(LEGACY_LINES))
         out.push(row(l));

package/dist/plan-commit.js

@@ -0,0 +1,90 @@
+import { spawnSync } from 'node:child_process';
+import { accessSync, constants, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { isAbsolute, join, resolve } from 'node:path';
+import { tryGit } from './git.js';
+/** Gabarit par défaut du message d'un commit de plan écrit dans une vague (L343 : inchangé depuis toujours). */
+export const PLAN_COMMIT_WAVE = 'plan: {lot} {action} (orchestrate {vague})';
+/** Gabarit par défaut hors vague (`spec reseal`) : pas de vague à citer. */
+export const PLAN_COMMIT_PLAIN = 'plan: {lot} {action}';
+/** Gabarit par défaut du commit de la fiche sourcée par la réponse du lead : type `docs`, déjà conventionnel (L343). */
+export const LEAD_ANSWER_COMMIT = 'docs({lot}): {action} (orchestrate {vague})';
+/** Les mots que le gabarit `plan.commit` de cadence.yaml peut employer. */
+export const PLAN_COMMIT_FIELDS = ['lot', 'action', 'vague'];
+/** Ce que cadence écrit dans un commit de plan, par action : une seule source pour la vague et pour le dry-run. */
+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). */
+    specGreen: 'acceptation verte, vert: true posé par cadence spec green',
+    resealed: (norm) => `test d'acceptation rescellé (${norm})`,
+    /** En minuscule : `subject-case` de config-conventional refuse une majuscule initiale (L343). */
+    leadAnswer: (ids) => `${ids.length > 1 ? 'règles' : 'règle'} ${ids.join(', ')} ${ids.length > 1 ? 'sourcées' : 'sourcée'} par la réponse du lead`,
+};
+/** Le message du commit de la fiche sourcée par la réponse du lead : le gabarit `plan.commit` du projet comme tout commit écrit par cadence, à défaut `docs(<lot>): …` (L343). */
+export function leadAnswerMessage(template, lot, ids, wave) {
+    return planCommitMessage(template ?? LEAD_ANSWER_COMMIT, { lot, action: PLAN_ACTIONS.leadAnswer(ids), wave });
+}
+/** Valide le gabarit `plan.commit` ; rend la raison du refus, null s'il est bon. */
+export function planCommitProblem(template) {
+    if (template.trim() === '')
+        return 'est vide';
+    if (/[\r\n]/.test(template))
+        return 'doit tenir sur une ligne';
+    if (!template.includes('{lot}'))
+        return 'doit contenir {lot} (le commit doit citer son lot)';
+    for (const m of template.matchAll(/\{([^{}]*)\}/g)) {
+        if (!PLAN_COMMIT_FIELDS.includes(m[1]))
+            return `{${m[1]}} inconnu (attendu : ${PLAN_COMMIT_FIELDS.map((f) => `{${f}}`).join(', ')})`;
+    }
+    return null;
+}
+/**
+ * Le message d'un commit de plan : le gabarit du projet (`plan.commit`), à défaut celui d'avant L343.
+ * Hors vague, un groupe entre parenthèses qui porte `{vague}` disparaît avec elle, au lieu de laisser « (orchestrate ) ».
+ */
+export function planCommitMessage(template, v) {
+    let t = template ?? (v.wave === undefined ? PLAN_COMMIT_PLAIN : PLAN_COMMIT_WAVE);
+    if (v.wave === undefined)
+        t = t.replace(/\s*\([^()]*\{vague\}[^()]*\)/g, '').replaceAll('{vague}', '');
+    return t.replaceAll('{lot}', () => v.lot).replaceAll('{vague}', () => v.wave ?? '').replaceAll('{action}', () => v.action);
+}
+/** Le hook commit-msg que git lancerait dans `root` (core.hooksPath compris, husky aussi) ; null s'il n'y en a pas d'exécutable. */
+export function commitMsgHook(root) {
+    const rel = tryGit(root, ['rev-parse', '--git-path', 'hooks/commit-msg'])?.trim();
+    if (!rel)
+        return null;
+    const path = isAbsolute(rel) ? rel : resolve(root, rel);
+    try {
+        accessSync(path, constants.X_OK);
+        return path;
+    }
+    catch {
+        return null;
+    }
+}
+/** Passe `message` au hook commit-msg réel de `root`. Null : accepté, ou aucun hook ; sinon ce que le hook a dit en refusant. */
+export function commitMsgRefusal(root, message) {
+    const hook = commitMsgHook(root);
+    if (!hook)
+        return null;
+    const dir = mkdtempSync(join(tmpdir(), 'cadence-commitmsg-'));
+    try {
+        const file = join(dir, 'COMMIT_EDITMSG');
+        writeFileSync(file, `${message}\n`);
+        const r = spawnSync(hook, [file], { cwd: root, encoding: 'utf8', timeout: 120_000 });
+        if (r.status === 0 && !r.error)
+            return null;
+        const lines = `${r.stdout ?? ''}${r.stderr ?? ''}`.split('\n').map((l) => l.replace(/\x1b\[[0-9;]*m/g, '').trim()).filter(Boolean);
+        const said = lines.filter((l) => l.includes('✖'));
+        return (said.length ? said.slice(0, 3) : lines.slice(-2)).join(' | ') || (r.error ? r.error.message : `code ${r.status}`);
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}

package/dist/plan.js

@@ -1,7 +1,15 @@
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
-import { dirname } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, rmSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
 import { isMap, isSeq, parseDocument } from 'yaml';
 import { isDay, toDay } from './dates.js';
+/** Délai de la commande `plan.onWrite` : une republication du plan, pas un build. */
+const ON_WRITE_TIMEOUT_MS = 120_000;
+/** Où va un avertissement de `save()` (la commande a réussi mais quelque chose cloche) : stderr, ou le `err` du CLI qui a lancé l'écriture. */
+let notice = (line) => void process.stderr.write(`${line}\n`);
+export function setPlanNotice(fn) {
+    notice = fn;
+}
 export const STATUSES = ['todo', 'doing', 'done', 'dropped'];
 export const GATE_INVALID = 'gate invalide : count: entier ≥ 1 et un critère spec: true ou screen: page attendus';
 export class RafError extends Error {
@@ -119,9 +127,35 @@ export class Plan {
     reloaded() {
         return Plan.load(this.path, this.settings);
     }
+    /**
+     * Écrit le plan, puis lance `plan.onWrite` s'il est déclaré. Chemin unique de toutes les écritures (raf, orchestrate, deliver, config set) :
+     * si la commande échoue, le plan et les fichiers qu'elle déclare reviennent tels qu'avant et l'erreur le dit (L346).
+     */
     save() {
         this.writable();
+        const hook = this.settings.onWrite;
+        const kept = hook ? [this.path, ...hook.files.map((f) => resolve(hook.cwd, f))].map((p) => [p, existsSync(p) ? readFileSync(p) : null]) : [];
         writeFileSync(this.path, this.doc.toString({ lineWidth: 0, indentSeq: this.indentSeq }));
+        if (!hook)
+            return;
+        const limit = hook.timeoutMs ?? ON_WRITE_TIMEOUT_MS;
+        const r = spawnSync('sh', ['-c', hook.command], { cwd: hook.cwd, encoding: 'utf8', timeout: limit, stdio: ['ignore', 'pipe', 'pipe'] });
+        if (r.status === 0) {
+            // Un chemin mal déclaré laisse le vrai fichier produit hors du commit du plan (le constat d'origine du lot) : le dire.
+            const missing = hook.files.filter((f) => !existsSync(resolve(hook.cwd, f)));
+            if (missing.length > 0)
+                notice(`raf: plan.onWrite a réussi mais le fichier déclaré est absent : ${missing.join(', ')} — vérifier plan.onWrite.files dans cadence.yaml`);
+            return;
+        }
+        for (const [p, content] of kept) {
+            if (content === null)
+                rmSync(p, { force: true });
+            else
+                writeFileSync(p, content);
+        }
+        const why = r.error ? r.error.code === 'ETIMEDOUT' ? `délai de ${limit / 1000} s dépassé` : r.error.message : `code ${r.status ?? r.signal}`;
+        const tail = `${r.stdout ?? ''}${r.stderr ?? ''}`.trim().split('\n').slice(-5).join(' | ');
+        throw new RafError(`plan.onWrite en échec (${hook.command}, ${why})${tail ? ` : ${tail}` : ''} — écriture refusée, plan inchangé`);
     }
     get project() {
         return String(this.doc.get('project') ?? this.settings.project ?? '');
@@ -188,13 +222,17 @@ export class Plan {
     get files() {
         return this.settings.files ?? [];
     }
+    /** Fichiers que produit `plan.onWrite` (L346), relatifs à la racine du dépôt : à commiter avec le plan, même s'ils n'étaient pas encore suivis. */
+    get produced() {
+        return this.settings.onWrite?.files ?? [];
+    }
     /** Fichier d'attendus QA du `qa-reviewer`, relatif à la racine du dépôt. */
     get qaExpectations() {
         return this.settings.qaExpectations ?? 'docs/qa/expectations.md';
     }
     /** Tout ce qui est tenu avec le plan sans être du travail : plan.files et le fichier d'attendus QA. Source unique de l'audit et de l'orchestrateur. */
     get maintained() {
-        return [...this.files, this.qaExpectations];
+        return [...new Set([...this.files, ...this.produced, this.qaExpectations])];
     }
     /**
      * Références citées par un texte. Format de raf : préfixe et numéro (`L3`, `L3/t1`). Autre format :

package/dist/ref/analyse.js

@@ -1,10 +1,10 @@
-import { existsSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { PACKAGE_ROOT } from '../orchestrate/snapshot.js';
 import { RafError } from '../plan.js';
 import { add } from './add.js';
 import { checkInventaire, readInventaire } from './check.js';
-import { assembler, parseSeuil, reconcilier } from './diff.js';
+import { assembler, parseSeuil, precedentDe, reconcilier, reprendreIds } from './diff.js';
 import { troisiemeRegard } from './regard.js';
 import { sessionDeRef } from './session.js';
 /** Plafond déclaré d'une lecture : au plus 20 pages rendues lues d'un coup (design §5, « Taille »). Au-delà, `--sections` en choisit moins. */
@@ -88,6 +88,8 @@ async function lireUne(c, nom, model) {
     const problems = schema.length > 0 ? schema : ecartsDeLecture(lecture, c.doc);
     if (problems.length > 0)
         return { kind: 'refus', problems };
+    if (nom === 'a')
+        reprendreIds(lecture, c.precedent); // la lecture A porte les ids que les lots citent ; B est réconciliée et renumérotée par `assembler`
     const usage = { tokens: r.tokens, modele: model, session: r.session };
     lecture.usage = usage;
     writeFileSync(file, `${JSON.stringify(lecture, null, 2)}\n`);
@@ -95,6 +97,31 @@ async function lireUne(c, nom, model) {
     return { kind: 'ok', lecture, file, usage, questions: Array.isArray(structured?.questions) ? structured.questions.map(String) : [] };
 }
 const confiancesDe = (lecture) => ['mesure', 'lu', 'incertain'].map((c) => [c, lecture.elements.filter((e) => e.confiance === c).length]).filter(([, n]) => n > 0).map(([c, n]) => `${c} : ${n}`).join(', ');
+/** Les fichiers d'un document que ce passage supprime ou réécrit, et où le lead a pu écrire ses `exclusions` (relatifs au dossier du document). */
+const FICHIERS_REMPLACES = ['inventaire.json', 'lectures/a.json', 'lectures/b.json'];
+/**
+ * Les `exclusions` écrites à la main dans les fichiers que ce passage va remplacer sont gardées à côté (`exclusions-<date>.json`, une clé par fichier) et
+ * dites au lead : `references.dir` est hors du dépôt, rien d'autre ne les retrouverait. Sans exclusion écrite, rien n'est écrit ni dit.
+ */
+function garderExclusions(docDir, now, out) {
+    const gardees = {};
+    for (const nom of FICHIERS_REMPLACES) {
+        try {
+            const x = JSON.parse(readFileSync(join(docDir, nom), 'utf8')).exclusions;
+            if (Array.isArray(x) && x.length > 0)
+                gardees[nom] = x;
+        }
+        catch {
+            // absent ou illisible : il n'y a rien à garder
+        }
+    }
+    const noms = Object.keys(gardees);
+    if (noms.length === 0)
+        return;
+    const file = join(docDir, `exclusions-${now.toISOString().replace(/[:.]/g, '-')}.json`);
+    writeFileSync(file, `${JSON.stringify(gardees, null, 2)}\n`);
+    out(`attention : ${Object.values(gardees).reduce((n, x) => n + x.length, 0)} exclusion(s) écrite(s) dans ${noms.join(', ')}, remplacé(s) par ce passage : gardée(s) dans ${file}`);
+}
 /**
  * `cadence ref analyse` : la chaîne — add, puis UNE lecture (une session de l'agent `reference-analyst`, `lectures/a.json`) ; avec `--double`, deux lectures
  * indépendantes (A et B, modèles possiblement différents), `ref diff` (réconciliation par le programme), le troisième regard sur ce qu'une seule lecture
@@ -119,13 +146,16 @@ export async function analyse(o) {
         throw new RafError(`ref analyse : aucune page rendue : rien à lire${sections}`);
     if (pages.length > LECTURE_PAGES_MAX)
         throw new RafError(`ref analyse : ${pages.length} pages ${o.sections === undefined ? 'rendues' : 'à lire (--sections et les figures qu\'elles citent)'}, plafond d'une lecture : ${LECTURE_PAGES_MAX} pages${sections}`);
-    const c = { o, slug, docDir, doc, pages };
+    // avant de supprimer ou de réécrire quoi que ce soit : l'inventaire, sinon la lecture A du passage précédent, donne ses ids à celui-ci
+    const precedent = precedentDe(join(docDir, 'inventaire.json'), join(docDir, 'lectures', 'a.json'));
+    const c = { o, slug, docDir, doc, pages, precedent };
     const refuse = (problems, prefixe = '') => {
         for (const p of problems)
             o.out(`✗ ${prefixe}${p}`);
         o.out(`${problems.length} écart(s)`);
         return 1;
     };
+    garderExclusions(docDir, o.now, o.out);
     if (!o.double) {
         // les fichiers d'une double lecture précédente ne passent pas pour ceux de ce passage : leur `usage.lectures.a` ne serait plus celui de `a.json`
         rmSync(join(docDir, 'lectures', 'b.json'), { force: true });
@@ -184,7 +214,7 @@ export async function analyse(o) {
         seuls.forEach((item, i) => (item.decision = r.decisions[i]));
         regard = r;
     }
-    const inv = assembler(la.lecture, lb.lecture, rec, regard !== undefined);
+    const inv = assembler(la.lecture, lb.lecture, rec, regard !== undefined, precedent);
     if (inv.elements.length === 0) {
         // tout ce que les lectures portent n'était porté que par une seule d'entre elles et le troisième regard l'a écarté : rien à écrire, ce n'est pas un défaut de cadence
         o.out(`${slug} : double lecture (A ${model}, B ${modelB}) — ${pagesLues(pages.length)} (plafond d'une lecture : ${LECTURE_PAGES_MAX})`);

package/dist/ref/command.js

@@ -17,6 +17,7 @@ import { referencesDir } from './store.js';
 const USAGE_ADD = 'usage : cadence ref add <document.pdf> [--sections 3-5,9] [--slug nom]';
 const USAGE_ANALYSE = 'usage : cadence ref analyse <document.pdf> [--sections 3-5,9] [--slug nom] [--model sonnet|opus|haiku] [--model-b sonnet|opus|haiku] [--seuil 30] [--double]';
 const USAGE_CHECK = 'usage : cadence ref check <inventaire.json | lecture.json>';
+const USAGE_COVERAGE = 'usage : cadence ref coverage <inventaire.json>';
 const USAGE_DIFF = 'usage : cadence ref diff <lecture-a.json> <lecture-b.json> [--out inventaire.json] [--seuil 30]';
 const USAGE_EVAL = 'usage : cadence ref eval <attendu.json | dossier> <lecture.json | dossier> [--json]';
 const USAGE_CORPUS = 'usage : cadence ref corpus <dossier> [--sans-rendu]';
@@ -66,7 +67,7 @@ export function refCommand(rest, values, root, io) {
     if (verb === 'corpus' && args.length === 1)
         return corpus(resolve(io.cwd, args[0]), values['sans-rendu'] === true, io);
     const others = (u) => u.replace('usage : ', '');
-    throw new RafError(verb === 'add' ? USAGE_ADD : verb === 'analyse' ? USAGE_ANALYSE : verb === 'measure' ? USAGE_MEASURE : verb === 'check' ? USAGE_CHECK : verb === 'diff' ? USAGE_DIFF : verb === 'eval' ? USAGE_EVAL : verb === 'corpus' ? USAGE_CORPUS : `${USAGE_ADD}\n       ${others(USAGE_ANALYSE)}\n       ${others(USAGE_MEASURE)}\n       ${others(USAGE_CHECK)}\n       ${others(USAGE_DIFF)}\n       ${others(USAGE_EVAL)}\n       ${others(USAGE_CORPUS)}`);
+    throw new RafError(verb === 'add' ? USAGE_ADD : verb === 'analyse' ? USAGE_ANALYSE : verb === 'measure' ? USAGE_MEASURE : verb === 'check' ? USAGE_CHECK : verb === 'diff' ? USAGE_DIFF : verb === 'eval' ? USAGE_EVAL : verb === 'corpus' ? USAGE_CORPUS : `${USAGE_ADD}\n       ${others(USAGE_ANALYSE)}\n       ${others(USAGE_MEASURE)}\n       ${others(USAGE_CHECK)}\n       ${others(USAGE_COVERAGE)}\n       ${others(USAGE_DIFF)}\n       ${others(USAGE_EVAL)}\n       ${others(USAGE_CORPUS)}`);
 }
 /** `ref corpus <dossier>` : un sous-dossier par piège (document.html, attendu.json, puis document.pdf et page-<n>.png sauf --sans-rendu). */
 async function corpus(dossier, sansRendu, io) {