@sylad/cadence 1.8.0 → 1.10.0

package/dist/config.js

@@ -2,6 +2,7 @@ import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { basename, dirname, isAbsolute, join, posix, relative, resolve } from 'node:path';
 import { parse } from 'yaml';
 import { isDay } from './dates.js';
+import { DEFAULT_TEST_PATTERNS } from './testgate.js';
 import { gitRoot } from './git.js';
 import { FIELDS, Plan, RafError, STATUSES } from './plan.js';
 const KEYS = ['path', 'project', 'since', 'ignore', 'files', 'lots', 'fields', 'statuses', 'estimates'];
@@ -44,7 +45,7 @@ function readQa(qa, file, workRoot) {
 /**
  * Clé `plan:` de cadence.yaml : où est le plan et, s'il est tenu par un autre outil, comment le lire.
  * `root` : la racine du dépôt de travail (celle du CLI), d'où se résout un chemin absolu de `qa.expectations`.
- * Null quand le fichier ou la clé manque — le plan est alors docs/plan/raf.yaml au format de raf.
+ * Null quand le fichier ou la clé manque — le plan est alors .cadence/raf.yaml (ou docs/plan/raf.yaml hérité) au format de raf.
  */
 export function readPlanConfig(file, root) {
     if (!existsSync(file))
@@ -89,6 +90,19 @@ export function readPlanConfig(file, root) {
         throw bad('path est vide');
     return { ...(p.path != null ? { path: String(p.path) } : {}), settings };
 }
+export const PLAN_DEFAULT = '.cadence/raf.yaml';
+export const PLAN_LEGACY = 'docs/plan/raf.yaml';
+/**
+ * Le plan par défaut d'un projet (L246) : .cadence/raf.yaml, versionné et jamais publié avec docs/ ; un docs/plan/raf.yaml hérité
+ * reste le plan tant qu'il n'est pas déplacé et que .cadence/raf.yaml n'existe pas. `legacy` : le plan hérité existe (lu, ou ignoré
+ * quand les deux existent) — c'est à l'appelant d'en parler.
+ */
+export function defaultPlan(root) {
+    const legacy = existsSync(join(root, PLAN_LEGACY));
+    if (existsSync(join(root, PLAN_DEFAULT)))
+        return { path: join(root, PLAN_DEFAULT), legacy: legacy ? 'ignored' : null };
+    return { path: join(root, legacy ? PLAN_LEGACY : PLAN_DEFAULT), legacy: legacy ? 'read' : null };
+}
 /**
  * Le chargeur du plan du projet dont `root` est la racine : le `cadence.yaml` est lu tout de suite (une erreur sort ici), le plan à
  * chaque appel. Une seule lecture de « où est le plan et comment le lire » pour l'orchestrateur, `lead tour` et le tirage de `--continue`.
@@ -96,8 +110,8 @@ export function readPlanConfig(file, root) {
 export function planLoader(root) {
     const configPath = join(root, 'cadence.yaml');
     const planConfig = readPlanConfig(configPath, root);
-    const planPath = resolve(root, planConfig?.path ?? 'docs/plan/raf.yaml');
-    return () => Plan.load(planPath, { ...planConfig?.settings, config: configPath });
+    // Le défaut est résolu à chaque appel : un plan déplacé (git mv) pendant une vague est suivi.
+    return () => Plan.load(planConfig?.path ? resolve(root, planConfig.path) : defaultPlan(root).path, { ...planConfig?.settings, config: configPath });
 }
 function parseFormat(p, bad) {
     const format = { lots: p.lots == null ? 'lots' : String(p.lots), fields: {}, statuses: {}, estimates: {} };
@@ -269,10 +283,10 @@ const EFFORTS = ['default', 'low', 'medium', 'high', 'xhigh', 'max'];
 export const EFFORT_STEPS = ['precheck', 'spec', 'maquette', 'fiche', 'accept', 'implement', 'fix', 'review', 'ux'];
 const MODELS = ['haiku', 'sonnet', 'opus'];
 const REVIEW_KEYS = ['threshold', 'light', 'full'];
-const ORCH_KEYS = ['start', 'verdict', 'test', 'build', 'accept', 'maquette', 'maquetteReviews', 'fiche', 'ux', 'precheck', 'prodAccess', 'spec', 'review', 'effort', 'permissionMode', 'addDirs', 'timeouts'];
+const ORCH_KEYS = ['start', 'verdict', 'test', 'build', 'accept', 'maquette', 'maquetteReviews', 'fiche', 'ux', 'precheck', 'prodAccess', 'worktrees', 'testGate', 'spec', 'review', 'effort', 'permissionMode', 'addDirs', 'timeouts'];
 /** Clé `orchestrate:` de cadence.yaml. Absente : les défauts (auto, 45 min d'implémentation, 25 min de revue). */
 export function readOrchestrateConfig(file) {
-    const config = { precheck: true, maquette: true, maquetteReviews: 3, fiche: true, precheckLocal: false, prodAccess: false, spec: { dir: 'docs/specs' }, review: { threshold: 0.25, light: 'sonnet', full: 'opus' }, effort: { precheck: 'low', spec: 'medium', maquette: 'high', fiche: 'medium', accept: 'medium', implement: 'medium', fix: 'medium', review: 'high', ux: 'high' }, permissionMode: 'auto', addDirs: [], timeouts: { work: 45 * 60_000, review: 25 * 60_000 } };
+    const config = { precheck: true, maquette: true, maquetteReviews: 3, fiche: true, precheckLocal: false, prodAccess: false, worktrees: false, spec: { dir: 'docs/specs' }, review: { threshold: 0.25, light: 'sonnet', full: 'opus' }, effort: { precheck: 'low', spec: 'medium', maquette: 'high', fiche: 'medium', accept: 'medium', implement: 'medium', fix: 'medium', review: 'high', ux: 'high' }, permissionMode: 'auto', addDirs: [], timeouts: { work: 45 * 60_000, review: 25 * 60_000 } };
     if (!existsSync(file))
         return config;
     let raw;
@@ -339,6 +353,34 @@ export function readOrchestrateConfig(file) {
             throw bad('prodAccess : true ou false attendu');
         config.prodAccess = o.prodAccess;
     }
+    if (o.worktrees != null) {
+        if (typeof o.worktrees !== 'boolean')
+            throw bad('worktrees doit être true ou false');
+        config.worktrees = o.worktrees;
+    }
+    if (o.testGate != null && o.testGate !== false) {
+        const g = o.testGate;
+        if (!isObject(g))
+            throw bad('testGate doit être false ou un objet { code, tests, except, threshold }');
+        for (const k of Object.keys(g))
+            if (!['code', 'tests', 'except', 'threshold'].includes(k))
+                throw bad(`testGate.${k} inconnu (attendu : code, tests, except, threshold)`);
+        const patterns = (key, fallback) => {
+            if (g[key] == null) {
+                if (fallback)
+                    return fallback;
+                throw bad(`testGate.${key} : au moins un motif de chemin attendu`);
+            }
+            const v = list(g[key]);
+            if (v.some((x) => !x.trim()) || (key !== 'except' && !v.length))
+                throw bad(`testGate.${key} : motifs de chemin non vides attendus`);
+            return v.map((x) => x.trim());
+        };
+        const threshold = g.threshold ?? 1;
+        if (typeof threshold !== 'number' || !Number.isInteger(threshold) || threshold < 1)
+            throw bad('testGate.threshold : entier supérieur ou égal à 1 attendu');
+        config.testGate = { code: patterns('code', null), tests: patterns('tests', DEFAULT_TEST_PATTERNS), except: patterns('except', []), threshold };
+    }
     if (o.spec != null) {
         if (!isObject(o.spec))
             throw bad('spec doit être un objet { dir, render }');
@@ -453,6 +495,9 @@ export function readDocsConfig(file) {
     catch (e) {
         throw new RafError(`${file} illisible : ${e.message.split('\n')[0]}`);
     }
+    if (raw?.describedBy != null) {
+        throw new RafError(`${file} : describedBy n'existe plus (L308) : les documents hors dépôt se déclarent dans docs.articles, { repo, file } relatif au projet`);
+    }
     const d = raw?.docs;
     if (d == null)
         return none;
@@ -506,3 +551,54 @@ export function readDocsConfig(file) {
     }
     return config;
 }
+/** Clé `references:` de cadence.yaml. */
+export function readReferencesConfig(file) {
+    if (!existsSync(file))
+        return {};
+    let raw;
+    try {
+        raw = parse(readFileSync(file, 'utf8'));
+    }
+    catch (e) {
+        throw new RafError(`${file} illisible : ${e.message.split('\n')[0]}`);
+    }
+    const r = raw?.references;
+    if (r == null)
+        return {};
+    if (!isObject(r))
+        throw new RafError(`${file} : references doit être un objet { dir }`);
+    for (const k of Object.keys(r))
+        if (k !== 'dir')
+            throw new RafError(`${file} : references.${k} inconnu (attendu : dir)`);
+    if (r.dir == null)
+        return {};
+    if (typeof r.dir !== 'string' || r.dir.trim() === '')
+        throw new RafError(`${file} : references.dir : chemin attendu`);
+    return { dir: r.dir.trim() };
+}
+/** Clé `migrate:` de cadence.yaml (L284) : `migrate.keep`. */
+export function readMigrateConfig(file) {
+    const none = { keep: [] };
+    if (!existsSync(file))
+        return none;
+    let raw;
+    try {
+        raw = parse(readFileSync(file, 'utf8'));
+    }
+    catch (e) {
+        throw new RafError(`${file} illisible : ${e.message.split('\n')[0]}`);
+    }
+    const m = raw?.migrate;
+    if (m == null)
+        return none;
+    if (!isObject(m))
+        throw new RafError(`${file} : migrate doit être un objet { keep }`);
+    for (const k of Object.keys(m))
+        if (k !== 'keep')
+            throw new RafError(`${file} : migrate.${k} inconnu (attendu : keep)`);
+    if (m.keep == null)
+        return none;
+    if (!Array.isArray(m.keep) || m.keep.some((x) => typeof x !== 'string' || !x.trim()))
+        throw new RafError(`${file} : migrate.keep doit être une liste de chemins ou de motifs non vides`);
+    return { keep: m.keep.map((x) => x.trim()) };
+}

package/dist/corrections.js

@@ -1,5 +1,6 @@
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { basename, join } from 'node:path';
+import { LOCAL_PRECHECK_UNREADABLE, PRECHECK_UNREADABLE } from './orchestrate/state.js';
 import { RafError } from './plan.js';
 /** Les causes d'une passe de correction (L165), dans l'ordre où le rapport les liste. */
 export const CAUSES = ['spec-floue', 'regle-inventee', 'derive-architecture', 'donnees-sql', 'bug-code', 'test-manquant', 'faux-constat'];
@@ -48,6 +49,23 @@ function usageOf(tokens) {
  * Lit TOUS les journaux de vague `<runs>/<vague>/<projet>--<lot>.json` lisibles (seuls un journal sans `steps` lisible ou, sous `until` ou `since`, une vague sans date de création lisible sont écartés) : c'est la lecture que partagent `readRuns` et `cadence perf` (L225), le filtre « session implement aboutie » n'est pas ici mais dans leurs prédicats (`implemented`). Chaque pas `fix` abouti est une passe, rattachée aux constats de la dernière revue qui la précède.
  * `until` : date ISO, ne lit que les vagues créées jusque-là et, dans chacune, les étapes terminées (`ended`) jusque-là ; une vague ou une étape sans date lisible est écartée. `since` : date ISO, ne garde que les vagues créées strictement après.
  */
+/**
+ * Verdict du contrôle préalable d'un journal : `precheckVerdict` (L288) ; pour un journal d'avant, relu de ce qu'il garde : le lot
+ * rendu « livrable déjà présent » est un « oui », celui qui porte le constat du précheck (`precheck`) un « partiel », tout autre
+ * lot dont l'étape precheck a abouti un « non ». Sans étape precheck aboutie, aucun verdict ; de même pour un journal qui garde l'avertissement
+ * d'un rapport illisible (L293) : sans verdict lisible, le lot n'est pas un « non ».
+ */
+function precheckVerdictOf(rec, steps) {
+    if (rec.precheckVerdict === 'oui' || rec.precheckVerdict === 'partiel' || rec.precheckVerdict === 'non')
+        return rec.precheckVerdict;
+    if (!steps.some((s) => s.kind === 'precheck' && s.status === 'ok'))
+        return undefined;
+    if (Array.isArray(rec.warnings) && rec.warnings.some((w) => typeof w === 'string' && w.startsWith(PRECHECK_UNREADABLE)))
+        return undefined;
+    if (typeof rec.outcome === 'string' && rec.outcome.startsWith('livrable déjà présent'))
+        return 'oui';
+    return typeof rec.precheck === 'string' && rec.precheck !== '' ? 'partiel' : 'non';
+}
 export function readJournals(runsDir, until, since) {
     const journals = [];
     if (!existsSync(runsDir))
@@ -85,8 +103,9 @@ export function readJournals(runsDir, until, since) {
                 // Une passe fix entre la revue et celle-ci a déjà traité ces constats : cette passe-ci (tests rouges) n'en a pas.
                 const handled = review ? fixSteps.some((f) => f.n > review.n && f.n < fix.n) : false;
                 const findings = review?.report && !handled ? findingsOf(readJson(join(waveDir, name, review.report))) : [];
-                return { key: `${wave}/${name}/${fix.n}`, project: rec.project, lot: rec.lot, visible: !!rec.visible, findings, commits: fix.commits ?? [], ...(fix.ended ? { fixEnded: fix.ended } : {}) };
+                return { key: `${wave}/${name}/${fix.n}`, project: rec.project, lot: rec.lot, visible: !!rec.visible, findings, commits: fix.commits ?? [], ...(fix.ended ? { fixEnded: fix.ended } : {}), ...(findings.length > 0 && review ? { reviewKind: review.kind } : {}) };
             });
+            const precheck = precheckVerdictOf(rec, steps);
             journals.push({
                 wave,
                 ...(waveCreated ? { waveCreated } : {}),
@@ -94,8 +113,11 @@ export function readJournals(runsDir, until, since) {
                 project: rec.project,
                 lot: rec.lot,
                 visible: !!rec.visible,
+                small: !!rec.small,
                 status: String(rec.status),
                 ...(typeof rec.budget === 'number' ? { budget: rec.budget } : {}),
+                ...(precheck ? { precheck } : {}),
+                ...(Array.isArray(rec.warnings) && rec.warnings.some((w) => typeof w === 'string' && w.startsWith(LOCAL_PRECHECK_UNREADABLE)) ? { localUnreadable: true } : {}),
                 steps: steps.map((s) => {
                     const usage = usageOf(s.tokens);
                     return { n: s.n, kind: s.kind, status: s.status, ...(typeof s.model === 'string' ? { model: s.model } : {}), ...(s.started ? { started: s.started } : {}), ...(s.ended ? { ended: s.ended } : {}), ...(typeof s.tokens?.counted === 'number' ? { counted: s.tokens.counted } : {}), ...(usage ? { usage } : {}) };
@@ -117,7 +139,7 @@ export function readRuns(runsDir, until, since) {
         if (!j.implemented)
             continue;
         lots.push({ project: j.project, lot: j.lot, visible: j.visible, fixes: j.passes.length });
-        for (const { fixEnded: _ended, ...pass } of j.passes)
+        for (const { fixEnded: _ended, reviewKind: _kind, ...pass } of j.passes)
             passes.push(pass);
     }
     return { lots, passes };

package/dist/deliver.js

@@ -1,7 +1,9 @@
 import { execFileSync, spawn } from 'node:child_process';
+import { readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { constants } from 'node:os';
+import { join } from 'node:path';
 import { parse } from 'yaml';
-import { onTermination, readProcs, SIGNAL_GRACE_MS, TreeTracker } from './proc.js';
+import { onTermination, readProcs, SIGNAL_GRACE_MS, SIGNAL_PENDING_MS, TreeTracker } from './proc.js';
 import { isPlanOnly } from './audit.js';
 import { headSha, isAncestor, onRemote, readCommits, repoStatus, resolveCommit } from './git.js';
 import { citedRefs } from './link.js';
@@ -15,6 +17,12 @@ export const POLL_VERIFY = 10_000;
 const CI_OK = new Set(['success', 'skipped', 'neutral']);
 const GH_TIMEOUT = 60_000;
 export const TIMED_OUT = 124;
+/** Sortie gardée d'une commande : de quoi retrouver ses dernières lignes. */
+const OUTPUT_KEPT = 8_192;
+/** Signaux que cadence écoute (proc.ts) : une racine qu'ils ont tuée laisse présager le même signal vers cadence. */
+const TERMINATION_SIGNALS = [constants.signals.SIGHUP, constants.signals.SIGINT, constants.signals.SIGTERM];
+/** Les lignes de la sortie ; une ligne réécrite par \r (barre de progression) ne garde que sa dernière image non vide. */
+const outputTail = (text) => text.split('\n').flatMap((l) => l.split('\r').filter((f) => f.trim() !== '').slice(-1));
 const codeText = (code) => (code === TIMED_OUT ? 'délai dépassé' : `code ${code}`);
 export function parseDeliverConfig(text, file) {
     let raw;
@@ -96,8 +104,12 @@ export function parseDeliverConfig(text, file) {
         deployTimeout: seconds('deployTimeout', 1800),
     };
 }
-/** Dépendances réelles : sh, gh, fetch, horloge. `read` : le relevé des processus du suivi (injectable pour les tests). */
-export function realDeps(root, read = readProcs) {
+/**
+ * Dépendances réelles : sh, gh, fetch, horloge. `read` : le relevé des processus du suivi, `graceMs` : le délai de grâce
+ * après Ctrl-C ou raccrochage, `pendingMs` : l'attente d'un signal encore en route après la sortie de la racine
+ * (injectables pour les tests : sous charge, une grâce de 2 s se mesure mal).
+ */
+export function realDeps(root, read = readProcs, graceMs = SIGNAL_GRACE_MS, pendingMs = SIGNAL_PENDING_MS) {
     const gh = (args) => {
         try {
             return execFileSync('gh', args, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: GH_TIMEOUT });
@@ -111,18 +123,44 @@ export function realDeps(root, read = readProcs) {
             throw new Error(String(err.stderr || err.message).trim().split('\n').slice(0, 3).join(' '));
         }
     };
+    let output = '';
     return {
+        lastOutput: () => outputTail(output),
         exec: (cmd, env, timeoutMs) => new Promise((resolve) => {
+            output = '';
+            // Écoute posée AVANT spawn : un Ctrl-C reçu pendant la première lecture du suivi (synchrone, dans le
+            // constructeur du TreeTracker) serait sinon traité par l'action par défaut, qui tue cadence sans nettoyer
+            // l'arbre. Le nettoyage ne tourne qu'au tour de boucle suivant, quand `tree` existe.
+            let tree = null;
+            // Terminaison en cours : exec ne rend pas la main avant qu'elle ne soit finie — sinon deliver libère
+            // le verrou pendant la grâce, alors que des descendants tournent encore.
+            let ending = null;
+            const forget = onTermination((sig) => {
+                if (!tree)
+                    return; // commande jamais lancée : rien à nettoyer
+                ending = sig === 'SIGTERM' ? Promise.resolve(tree.kill()) : tree.end(graceMs);
+                return ending;
+            });
             const child = spawn('sh', ['-c', cmd], {
                 cwd: root,
                 env: { ...process.env, ...env },
-                stdio: ['ignore', 'inherit', 'inherit'],
+                // La sortie passe par cadence (recopiée à l'identique) pour que la raison d'un échec en garde la fin.
+                stdio: ['ignore', 'pipe', 'pipe'],
                 // PAS de groupe détaché : la commande reste dans le groupe de premier plan et la session de cadence.
                 // Ctrl-C et le raccrochage l'atteignent avec cadence, et /dev/tty reste là pour ssh, sudo, pinentry.
             });
+            const relay = (from, to) => from.on('data', (chunk) => {
+                to.write(chunk);
+                output = (output + chunk.toString('utf8')).slice(-OUTPUT_KEPT);
+            });
+            relay(child.stdout, process.stdout);
+            relay(child.stderr, process.stderr);
             const pid = child.pid;
             if (pid === undefined) {
-                child.once('error', () => resolve(127));
+                child.once('error', () => {
+                    forget();
+                    resolve(127);
+                });
                 return;
             }
             // L'arbre de la commande est suivi pendant toute son exécution (relevé périodique, pid + heure de
@@ -132,29 +170,38 @@ export function realDeps(root, read = readProcs) {
             // qu'une seconde livraison prend le verrou libéré ou périmé. Ctrl-C et raccrochage : l'arbre a déjà
             // reçu le signal du terminal, un court délai de grâce laisse finir ses trap (et git son index.lock)
             // avant le kill ; SIGTERM (à cadence seul) et le délai : kill immédiat.
-            const tree = new TreeTracker(pid, read, () => process.stderr.write('deliver : relevé des processus indisponible — le kill n\'est dégradé que tant que le relevé échoue : seule la commande racine sera tuée, ses descendants survivront\n'), () => process.stderr.write('deliver : kill replié sur la commande racine faute de relevé des processus — des descendants ont pu survivre\n'));
-            // Terminaison en cours : exec ne rend pas la main avant qu'elle ne soit finie — sinon deliver libère
-            // le verrou pendant la grâce, alors que des descendants tournent encore.
-            let ending = null;
-            const forget = onTermination((sig) => (ending = sig === 'SIGTERM' ? Promise.resolve(tree.kill()) : tree.end(SIGNAL_GRACE_MS)));
+            tree = new TreeTracker(pid, read, () => process.stderr.write('deliver : relevé des processus indisponible — le kill n\'est dégradé que tant que le relevé échoue : seule la commande racine sera tuée, ses descendants survivront\n'), () => process.stderr.write('deliver : kill replié sur la commande racine faute de relevé des processus — des descendants ont pu survivre\n'));
+            const tracker = tree;
             let timedOut = false;
             const timer = setTimeout(() => {
                 timedOut = true;
-                tree.kill();
+                tracker.kill();
             }, Math.max(1_000, timeoutMs));
             child.once('exit', (code, signal) => {
                 clearTimeout(timer);
-                tree.rootExited(); // son pid peut être repris : plus d'adoption tardive de la racine pendant la grâce
+                tracker.rootExited(); // son pid peut être repris : plus d'adoption tardive de la racine pendant la grâce
                 const result = timedOut ? TIMED_OUT : signal ? 128 + (constants.signals[signal] ?? 0) : (code ?? 1);
                 const settle = () => {
-                    tree.stop();
+                    tracker.stop();
                     forget();
                     resolve(result);
                 };
-                if (ending)
-                    void ending.then(settle);
-                else
-                    settle();
+                // Un Ctrl-C part au groupe entier : la racine peut mourir et sa sortie être traitée avant que le SIGINT
+                // adressé à cadence ne le soit. Retirer l'écoute à cet instant le perdrait (tracker.end jamais joué, un
+                // descendant qui ignore SIGINT survivrait, un second Ctrl-C tuerait cadence sans libérer le verrou) : on
+                // attend le signal en route, au plus pendantMs, tant que des processus suivis vivent OU que la racine est
+                // elle-même morte d'un signal de terminaison (ou sortie 128 + ce signal) — curl tué par le Ctrl-C.
+                const terminated = !timedOut && TERMINATION_SIGNALS.includes(result - 128);
+                const deadline = Date.now() + pendingMs;
+                const next = () => {
+                    if (ending)
+                        void ending.then(settle);
+                    else if ((!terminated && tracker.alive().length === 0) || Date.now() >= deadline)
+                        settle();
+                    else
+                        setTimeout(next, 20);
+                };
+                next();
             });
         }),
         gh: (sha) => JSON.parse(gh(['run', 'list', '--commit', sha, '--json', 'name,status,conclusion'])),
@@ -179,7 +226,7 @@ function substitute(text, sha) {
     return text.replaceAll('${SHA}', sha).replaceAll('${SHORT}', sha.slice(0, 7));
 }
 /** Argument rendu tel quel au script par sh, quels que soient ses espaces, guillemets ou jokers. */
-function shellQuote(arg) {
+export function shellQuote(arg) {
     return /^[A-Za-z0-9_@%+=:,./-]+$/.test(arg) ? arg : `'${arg.replaceAll("'", `'\\''`)}'`;
 }
 export function describeCheck(c, sha) {
@@ -202,11 +249,13 @@ export async function deliver(ctx, deps) {
         return refuse('des arguments ne se passent qu\'à un script de projet (deliver.script dans cadence.yaml)');
     }
     const script = config.script === undefined ? null : [config.script, ...ctx.args.map(shellQuote)].join(' ');
+    // --sha livre un commit poussé et ne lit pas l'arbre : un fichier modifié (le plan après raf done) n'y change rien.
     const repo = repoStatus(ctx.root);
-    if (repo.dirty && !config.allowDirty)
-        return refuse(`${repo.dirty} fichier(s) suivi(s) modifié(s) : commiter et pousser d'abord`);
-    if (repo.dirty)
-        err(`deliver : ${repo.dirty} fichier(s) suivi(s) modifié(s) : non livré(s), seul ${sha.slice(0, 7)} l'est (allowDirty)`);
+    const dirty = ctx.sha === undefined ? repo.dirty : 0;
+    if (dirty && !config.allowDirty)
+        return refuse(`${dirty} fichier(s) suivi(s) modifié(s) : commiter et pousser d'abord`);
+    if (dirty)
+        err(`deliver : ${dirty} fichier(s) suivi(s) modifié(s) : non livré(s), seul ${sha.slice(0, 7)} l'est (allowDirty)`);
     if (!onRemote(ctx.root, sha))
         return refuse(`${sha.slice(0, 7)} non poussé : la CI n'a rien construit (git push)`);
     const lock = readLock(ctx.state);
@@ -258,11 +307,11 @@ export async function deliver(ctx, deps) {
     if (!taken)
         return refuse('une autre livraison vient de démarrer');
     try {
-        const fail = (msg) => {
+        const fail = (msg, cls, tail = []) => {
             err(`deliver : ${msg}`);
             // Une livraison rouge s'inscrit au journal des rouges (perf) ; son écriture ne change ni le code ni le message d'échec.
             try {
-                appendFailedDelivery(ctx.state, ctx.today, sha, msg);
+                appendFailedDelivery(ctx.state, ctx.today, sha, msg, cls, tail);
             }
             catch (e) {
                 err(`deliver : journal des livraisons rouges non écrit : ${e.message}`);
@@ -270,35 +319,74 @@ export async function deliver(ctx, deps) {
             return 1;
         };
         out(`Livraison de ${env.CADENCE_SHORT} (${branch})`);
+        let declared = null;
         if (script !== null) {
             out(`→ script du projet : ${script}`);
-            const code = await deps.exec(script, env, config.deployTimeout * 1000);
-            if (code !== 0)
-                return fail(`script de livraison en échec (${codeText(code)}) : ${script}`);
+            // Le script qui déploie un autre commit que CADENCE_SHA y écrit son sha : cadence ne le devine pas.
+            const file = join(ctx.state, `deployed-${process.pid}`);
+            try {
+                writeFileSync(file, '');
+                const code = await deps.exec(script, { ...env, CADENCE_DEPLOYED_FILE: file }, config.deployTimeout * 1000);
+                // Code 2 : le script a refusé avant d'agir (même convention que deliver) ; tout autre échec est un déploiement qui a cassé.
+                if (code !== 0)
+                    return fail(`script de livraison en échec (${codeText(code)}) : ${script}`, code === 2 ? 'refus' : 'deploiement', deps.lastOutput?.());
+                const text = readFileSync(file, 'utf8').trim();
+                if (text !== '') {
+                    // Un sha seulement : HEAD ou une branche seraient résolus après le script, au commit d'un autre.
+                    declared = /^[0-9a-f]{7,40}$/i.test(text) ? resolveCommit(ctx.root, text) : null;
+                    if (declared === null)
+                        return fail(`CADENCE_DEPLOYED_FILE : « ${text.split('\n')[0].slice(0, 80)} » n'est pas un sha de commit du dépôt (le script doit y écrire le sha hexadécimal qu'il a déployé, ni HEAD ni une branche, ou rien)`, 'deploiement');
+                }
+            }
+            catch (e) {
+                return fail(`CADENCE_DEPLOYED_FILE illisible : ${e.message}`, 'deploiement');
+            }
+            finally {
+                rmSync(file, { force: true });
+            }
         }
         else {
             const ci = await waitCi(ctx, deps, sha, env);
+            // Seule une commande de CI a une sortie : pour `ci: github`, lastOutput serait celle d'une commande antérieure.
             if (ci)
-                return fail(ci);
+                return fail(ci, 'ci', typeof config.ci === 'object' ? deps.lastOutput?.() : []);
             for (const [i, cmd] of config.deploy.entries()) {
                 out(`→ déploiement ${i + 1}/${config.deploy.length} : ${cmd}`);
                 const code = await deps.exec(cmd, env, config.deployTimeout * 1000);
                 if (code !== 0)
-                    return fail(`déploiement en échec (${codeText(code)}) : ${cmd}`);
+                    return fail(`déploiement en échec (${codeText(code)}) : ${cmd}`, 'deploiement', deps.lastOutput?.());
             }
         }
         const failed = await verifyAll(ctx, deps, sha, env);
         if (failed)
-            return fail(failed);
-        // Un script de projet peut commiter pendant la livraison (horodatage d'une entrée Nouveautés) :
-        // ce qu'il a livré est alors la nouvelle tête, pas le sha de départ.
-        const head = script === null || !atHead ? sha : (headSha(ctx.root) ?? sha);
-        const moved = head !== sha && isAncestor(ctx.root, sha, head);
-        const final = moved ? head : sha;
+            return fail(failed.message, 'verification', failed.tail);
+        // Ce qui est journalisé : le sha que le script déclare (CADENCE_DEPLOYED_FILE) l'emporte. Sans déclaration, hors vague, un script qui a commité
+        // pendant la livraison (horodatage d'une entrée Nouveautés) a livré la nouvelle tête ; pendant une vague on ne devine plus qui a commité
+        // (le script, un lot en cours, un commit de plan) : le journal garde le sha de départ et l'avertissement le dit.
+        let final = sha;
+        let how = 'sha';
+        if (declared !== null && declared !== sha) {
+            final = declared;
+            how = 'declared';
+        }
+        else if (declared === null && script !== null) {
+            const head = headSha(ctx.root);
+            if (ctx.duringWave) {
+                if (head !== null && head !== head0) {
+                    err(`deliver : la tête a avancé pendant la livraison ; sans sha déclaré par le script (CADENCE_DEPLOYED_FILE), le journal garde ${env.CADENCE_SHORT}`);
+                }
+            }
+            else if (atHead && head !== null && head !== sha && isAncestor(ctx.root, sha, head)) {
+                final = head;
+                how = 'moved';
+            }
+        }
         const ids = deliveredIds(ctx, lastDelivery(ctx.state), final);
         const delivered = deliveredLots(ctx, ids, lastDelivery(ctx.state), final);
         appendDelivery(ctx.state, ctx.today, final);
-        if (moved)
+        if (how === 'declared')
+            out(`✓ livré : ${final.slice(0, 7)} (sha déclaré par le script)`);
+        else if (how === 'moved')
             out(`✓ livré : ${final.slice(0, 7)} (tête déplacée par le script depuis ${env.CADENCE_SHORT})`);
         else
             out(`✓ livré${config.verify.length ? ' et vérifié' : ''} : ${env.CADENCE_SHORT}`);
@@ -407,7 +495,7 @@ async function verifyAll(ctx, deps, sha, env) {
         ctx.out(`→ vérification ${i + 1}/${ctx.config.verify.length} : ${label}`);
         const reason = await retryCheck(c, deps, sha, env, deadline, () => deadline - deps.now());
         if (reason !== null)
-            return `vérification en échec après ${ctx.config.verifyTimeout} s : ${label} — ${reason}`;
+            return { message: `vérification en échec après ${ctx.config.verifyTimeout} s : ${label} — ${reason}`, tail: c.command !== undefined ? (deps.lastOutput?.() ?? []) : [] };
     }
     return null;
 }

package/dist/docsync.js

@@ -1,3 +1,4 @@
+import { resolve } from 'node:path';
 import { changedFiles } from './git.js';
 /** Motif de chemin : `*` reste dans un dossier, `**` le traverse, `?` un caractère, un `/` final prend tout le dossier ; sinon chemin exact. */
 export function docSyncMatcher(pattern) {
@@ -15,9 +16,9 @@ export function docSyncSet(patterns) {
     const no = patterns.filter((p) => p.startsWith('!')).map((p) => docSyncMatcher(p.slice(1)));
     return (file) => yes.some((m) => m(file)) && !no.some((m) => m(file));
 }
-/** Fichiers modifiés par un ensemble de commits, sans doublon. */
-export function filesOf(root, commits) {
-    return new Set(commits.flatMap((c) => changedFiles(root, c.sha)));
+/** Fichiers modifiés par un ensemble de commits, sans doublon ; `withoutDeleted` écarte les fichiers que les commits suppriment. */
+export function filesOf(root, commits, opts = {}) {
+    return new Set(commits.flatMap((c) => changedFiles(root, c.sha, opts)));
 }
 /** Les règles que ces fichiers enfreignent : ils touchent `paths` sans qu'aucun `docs` ne soit parmi eux. */
 export function docSyncGaps(rules, files) {
@@ -55,3 +56,18 @@ export function docSyncBrief(rules, gaps) {
         ...gaps.map((g) => `- ${listFiles(g.touched)} changed, but none of ${g.rule.docs.join(', ')} was touched`),
     ].join('\n');
 }
+/** Dossier du dépôt qui porte un document hors dépôt : `repo` relatif à la racine du projet, ou absolu (résolu tel quel). */
+export const articleRepoDir = (root, rule) => resolve(root, rule.repo);
+/**
+ * Consigne du bibliothécaire (L306, L308) sur les documents hors dépôt : seulement ceux que la configuration déclare (`docs.articles` du cadence.yaml du projet).
+ * Vide sans entrée. Le dépôt du document est ouvert à la session en lecture (--add-dir) ; le bibliothécaire ne l'écrit pas : il propose un lot pour le plan de ce dépôt.
+ */
+export function articlesBrief(root, rules) {
+    if (!rules.length)
+        return '';
+    return [
+        'Documents outside this repository, declared by the configuration (docs.articles of cadence.yaml): the project is also described by',
+        ...rules.map((r) => `- \`${r.file}\` of the repository \`${r.repo}\` (${articleRepoDir(root, r)}, open to this session for reading)`),
+        'If the change makes one of them false or leaves it out, do not edit it and do not touch the plan of that repository: write a proposed lot (a title, then the file, the passage and the sentence to change) and put it in the "resume" of your report, starting with « lot proposé ». Read it to be exact; read it only.',
+    ].join('\n');
+}

package/dist/git.js

@@ -12,6 +12,16 @@ export function gitRoot(cwd) {
         return null;
     }
 }
+/** Vrai quand `path` (relatif à `root`) est suivi par git : `git mv` échoue (code 128) sur un fichier non suivi. */
+export function isTracked(root, path) {
+    try {
+        git(root, ['ls-files', '--error-unmatch', '--', path]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 const FIELD = '\x1f';
 const RECORD = '\x1e';
 /** Commits reachable from HEAD, newest first. Empty when the repo has no commit yet. */
@@ -83,10 +93,13 @@ export function syncIndexWithHead(cwd, file) {
     if (same(['HEAD']) && !same(['--cached']))
         stage(cwd, file);
 }
-/** Fichiers modifiés par un commit, relatifs à la racine du dépôt (noms accentués ou à espaces compris). */
-export function changedFiles(cwd, sha) {
+/**
+ * Fichiers modifiés par un commit, relatifs à la racine du dépôt (noms accentués ou à espaces compris). `withoutDeleted` écarte ceux que
+ * le commit supprime (`--diff-filter=d`) : un fichier supprimé n'est plus du code à tester.
+ */
+export function changedFiles(cwd, sha, opts = {}) {
     // -z : noms séparés par NUL, jamais échappés ; quotepath=off en plus pour les sorties qui citeraient quand même.
-    return git(cwd, ['-c', 'core.quotepath=off', 'diff-tree', '--root', '--no-commit-id', '--name-only', '-r', '-z', sha]).split('\0').filter(Boolean);
+    return git(cwd, ['-c', 'core.quotepath=off', 'diff-tree', '--root', '--no-commit-id', '--name-only', '-r', '-z', ...(opts.withoutDeleted ? ['--diff-filter=d'] : []), sha]).split('\0').filter(Boolean);
 }
 /** Contenu d'un fichier à un commit (`<sha>^` pour l'état d'avant) ; null s'il n'existe pas à ce commit. */
 export function fileAt(cwd, rev, file) {