@sylad/cadence 1.13.0 → 1.14.1

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,88 @@
+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`,
+    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) {

package/dist/ref/coverage.js

@@ -0,0 +1,136 @@
+import { resolve } from 'node:path';
+import { RafError } from '../plan.js';
+import { isProgramNote } from '../orchestrate/decisions.js';
+import { fichesDuDossier } from '../spec.js';
+import { checkInventaire, readInventaire, TYPES } from './check.js';
+/** Un id d'élément d'inventaire (`<slug>#<type>-<n>`, R9 de `ref check`) tel qu'un lot le cite dans son titre, son objectif ou ses notes. */
+const ID_SOURCE = `[a-z0-9]+(?:-[a-z0-9]+)*#(?:${TYPES.join('|')})-[1-9]\\d*`;
+const ID_PATTERN = new RegExp(ID_SOURCE, 'g');
+/** Une ligne de `perimetre.hors_perimetre` d'une fiche qui justifie un élément non pris : `<id> : <raison>`. */
+const JUSTIFICATION = new RegExp(`^\\s*(${ID_SOURCE})\\s*:\\s*(\\S.*)$`);
+/** Les ids d'éléments d'inventaire cités dans un texte, sans doublon, dans l'ordre. */
+export function idsInText(text) {
+    return [...new Set(text.match(ID_PATTERN) ?? [])];
+}
+/**
+ * Les ids qu'un lot cite : son titre, son objectif (`goal:`) et les notes que le lead a écrites sur le lot. Les notes que le programme pose (titre remplacé,
+ * mineur de revue, hypothèses…) et celles des sous-tâches ne comptent pas : elles citent ce que le lot ne couvre plus ou ne couvre pas, et c'est le lot qui est fait ou non.
+ */
+export function lotIds(lot) {
+    return idsInText([lot.title, lot.goal ?? '', ...lot.notes.map((n) => n.text).filter((t) => !isProgramNote(t))].join('\n'));
+}
+/** Les éléments que la fiche d'un lot justifie comme non pris (`<id> : <raison>` dans `sujet.perimetre.hors_perimetre`), par id. */
+export function nonPris(repo, specDir, lotId) {
+    const out = new Map();
+    const doc = fichesDuDossier(repo, specDir).find(({ doc }) => doc.sujet?.lot === lotId)?.doc;
+    const sujet = doc?.sujet;
+    const lignes = sujet?.perimetre?.hors_perimetre;
+    for (const l of Array.isArray(lignes) ? lignes : []) {
+        const m = typeof l === 'string' ? JUSTIFICATION.exec(l) : null;
+        if (m)
+            out.set(m[1], m[2].trim());
+    }
+    return out;
+}
+/** Consigne des briefs d'un lot qui cite des éléments d'un document de référence : le spec-writer les prend ou justifie, le ux-reviewer les vérifie sur l'écran fini. */
+export function referenceIdsText(role, ids) {
+    if (!ids.length)
+        return '';
+    const list = ids.map((id) => `- \`${id}\``).join('\n');
+    if (role === 'spec') {
+        return [
+            'The lot covers these elements of a reference document (ids of its `inventaire.json`, `<slug>#<type>-<n>`):',
+            list,
+            'Take each one into the sheet: the field, rule or state that shows it quotes its id in its `source` (e.g. `source: "exemple#texte-3"`). An element you do not take is justified, one line `<id> : <reason>` — in the report under "choix", and in `perimetre.hors_perimetre` when the sheet has a back part. An id you leave out without a reason is a gap the review reads as a finding. `cadence ref coverage` reads the `hors_perimetre` lines: an element so justified is not covered by your lot, it stays a gap until the lead writes its exclusion or another lot takes it.',
+        ].join('\n');
+    }
+    return [
+        'The lot covers these elements of a reference document (ids of its `inventaire.json`):',
+        list,
+        'On the finished screen, verify each one: it is visible (or reachable) in the state where the sheet puts it, its text, role and place are those of the element, and it is in the captures you take. An element missing or different on the running screen is a finding naming its id; an element the sheet justified as not taken is not one.',
+    ].join('\n');
+}
+/** Ce qui désigne un élément à l'œil : son libellé, sa question, son nom… (rien pour un jeton ou une table sans nom). */
+function label(e) {
+    const text = [e.libelle, e.question, e.nom, e.contenu, e.figure, e.valeur].find((v) => typeof v === 'string' || typeof v === 'number');
+    return text === undefined ? '' : ` « ${String(text).slice(0, 60)} »`;
+}
+function where(e) {
+    const source = e.source;
+    const zone = source.zone ? ` zone ${source.zone.x},${source.zone.y},${source.zone.l},${source.zone.h}` : '';
+    return `p.${source.page}${zone}`;
+}
+/**
+ * Calcule la couverture d'un inventaire valide par les lots du plan (fait, abandonné compté pour rien) et par ses exclusions écrites. Un lot fait dont la fiche
+ * justifie un élément comme non pris (`justifies`) ne le couvre pas : l'élément reste un écart tant que le lead ne l'a pas exclu par écrit ou fait par un autre lot.
+ */
+export function computeCoverage(inventaire, lots, justifies = () => new Map()) {
+    const elements = inventaire.elements;
+    const known = new Set(elements.map((e) => e.id));
+    const byId = new Map();
+    for (const lot of lots)
+        for (const id of lotIds(lot))
+            if (known.has(id))
+                byId.set(id, [...(byId.get(id) ?? []), { id: lot.id, status: lot.status }]);
+    const problems = [];
+    const excluded = new Set();
+    const raw = inventaire.exclusions;
+    if (raw !== undefined && !Array.isArray(raw))
+        problems.push('exclusions : un tableau [{ id, raison }] est attendu');
+    else
+        raw?.forEach((x, i) => {
+            const o = typeof x === 'object' && x !== null ? x : {};
+            if (typeof o.id !== 'string' || !known.has(o.id))
+                problems.push(`exclusions[${i}].id : ${String(o.id)} ne désigne aucun élément de l'inventaire`);
+            else if (typeof o.raison !== 'string' || o.raison.trim() === '')
+                problems.push(`exclusions[${i}].raison : la raison de l'exclusion de ${o.id} est obligatoire`);
+            else
+                excluded.add(o.id);
+        });
+    const gaps = [];
+    let done = 0;
+    for (const e of elements) {
+        const id = e.id;
+        const mine = (byId.get(id) ?? []).filter((l) => l.status !== 'dropped');
+        const faits = mine.filter((l) => l.status === 'done');
+        const pris = faits.filter((l) => !justifies(l.id).has(id));
+        if (pris.length > 0)
+            done++;
+        else if (!excluded.has(id)) {
+            const reason = faits.length
+                ? `justifié non pris par la fiche de ${faits.map((l) => `${l.id} : ${justifies(l.id).get(id)}`).join(' ; ')}, sans exclusion écrite`
+                : mine.length ? `lot non fait (${mine.map((l) => `${l.id} ${l.status}`).join(', ')})` : 'aucun lot, aucune exclusion écrite';
+            gaps.push({ id, text: `${id} (${e.type} ${where(e)}${label(e)}) : ${reason}` });
+        }
+    }
+    return { gaps, problems, total: elements.length, done, excluded: elements.length - done - gaps.length };
+}
+const USAGE = 'usage : cadence ref coverage <inventaire.json>';
+/** `cadence ref coverage <inventaire.json>` : l'inventaire de `--double` ou la lecture de `lectures/a.json` (le défaut de `ref analyse`) ; 0 si tout élément a un lot fait ou une exclusion écrite, 1 sinon, 2 pour un appel mal formé ou un fichier qui n'est pas un inventaire ou une lecture valide. Sans modèle, sans outil système. */
+export function coverageCommand(args, loadPlan, io, fiches) {
+    if (args.length !== 1)
+        throw new RafError(USAGE);
+    const path = resolve(io.cwd, args[0]);
+    const inventaire = readInventaire(path);
+    const invalid = checkInventaire(inventaire);
+    if (invalid.length > 0)
+        throw new RafError(`ref coverage : ${path} n'est ni un inventaire ni une lecture valide (${invalid.length} écart(s), voir cadence ref check) : ${invalid[0]}`);
+    const cache = new Map();
+    const justifies = (lotId) => {
+        if (!cache.has(lotId))
+            cache.set(lotId, nonPris(fiches.repo, fiches.specDir, lotId));
+        return cache.get(lotId);
+    };
+    const c = computeCoverage(inventaire, loadPlan().lots(), justifies);
+    for (const p of c.problems)
+        io.out(`✗ ${p}`);
+    for (const g of c.gaps)
+        io.out(`✗ ${g.text}`);
+    const left = c.gaps.length + c.problems.length;
+    if (left > 0) {
+        io.out(`${c.gaps.length} élément(s) sans lot fait ni exclusion écrite${c.problems.length ? `, ${c.problems.length} exclusion(s) refusée(s)` : ''} sur ${c.total}`);
+        return 1;
+    }
+    io.out(`couverture complète : ${c.total} éléments (${c.done} par un lot fait, ${c.excluded} exclus avec leur raison)`);
+    return 0;
+}