@sylad/cadence 0.2.0 → 0.5.0

package/dist/cli.js

@@ -1,16 +1,17 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
 import { parseArgs } from 'node:util';
-import { check } from './check.js';
-import { audit, auditSince, exemptPlanOnly, nextUp } from './audit.js';
+import { readPlanConfig, readSessionConfig } from './config.js';
+import { audit, exemptPlanOnly, isPlanOnly, lotWork, nextUp, planCommits, unreviewedWork } from './audit.js';
+import { short } from './check.js';
 import { isDay, toDay } from './dates.js';
 import { deliver, parseDeliverConfig, realDeps } from './deliver.js';
 import { ganttData, renderGantt } from './gantt.js';
 import { gitRoot, readCommits } from './git.js';
 import { installHook } from './hook.js';
 import { linkCommits } from './link.js';
-import { buildNews, loadEntries, newEntry, newsData, newsIssues } from './news.js';
-import { extractRefs, Plan, RafError, STATUSES } from './plan.js';
+import { buildNews, loadEntries, newEntry, newsData, newsIssues, stampEntries } from './news.js';
+import { Plan, RafError, STATUSES } from './plan.js';
 import { schedule } from './schedule.js';
 import { AGENTS_DIR, installAgents, installSkills, SKILLS_DIR } from './skills.js';
 import { sessionClose, sessionStart } from './session.js';
@@ -23,16 +24,21 @@ const HELP = `raf — plan « reste à faire » versionné dans le dépôt, reli
   raf note <id> "texte"
   raf ux enable         revue UX obligatoire avant « done » pour les lots --visible
   raf ux <id> "verdict" enregistre la revue d'ergonomie du lot (agent ux-reviewer)
+  raf review enable     revue de code obligatoire avant « done » pour les lots qui ont des commits
+  raf review <id> "verdict" enregistre la revue de code du lot (agent code-reviewer)
+  raf commits <id>      les commits du lot que compte la porte de revue de code, du plus ancien au plus récent
   raf now               ce qui est en cours, la suite, les derniers terminés
   raf list [--status todo|doing|done|dropped]
   raf check [--since date] [--idle 7]   (défaut : date « since » du plan) code 1 s'il y a des écarts
   raf gantt [-o docs/plan/gantt.html]
   raf hook install
-  raf news new <lot…> [--title t] | list | check | build [-o dossier]   (aussi « cadence news … »)
+  raf news new <lot…> [--title t] | list | check | stamp | build [-o dossier]   (aussi « cadence news … »)
 
 Un commit appartient à un lot quand son message cite l'identifiant : « feat(L3): … », « L3/t1 ».
 Un lot --visible attend une entrée Nouveautés (docs/nouveautes/, --dir) avec capture ; raf check le vérifie.
 Un texte qui commence par « - » se passe après « -- » : raf note L1 -- "-5 %".
+Le plan est docs/plan/raf.yaml, ou celui que nomme « plan: » dans cadence.yaml ; un plan tenu par un
+autre outil se lit sans migration (correspondance des champs, voir le README) et reste en lecture seule.
 Options communes : --file chemin (ou RAF_FILE), RAF_TODAY=AAAA-MM-JJ pour figer la date.`;
 export function run(argv, io) {
     try {
@@ -78,6 +84,7 @@ function dispatch(argv, io) {
             output: { type: 'string', short: 'o' },
             config: { type: 'string' },
             'dry-run': { type: 'boolean' },
+            sha: { type: 'string' },
             help: { type: 'boolean', short: 'h' },
         },
     });
@@ -90,7 +97,13 @@ function dispatch(argv, io) {
     if (!isDay(today))
         throw new RafError(`RAF_TODAY invalide : ${today} (attendu AAAA-MM-JJ)`);
     const root = gitRoot(io.cwd) ?? io.cwd;
-    const planPath = resolve(io.cwd, values.file ?? io.env.RAF_FILE ?? join(root, 'docs/plan/raf.yaml'));
+    // cadence.yaml peut dire où est le plan et, s'il est tenu par un autre outil, comment le lire.
+    const configPath = resolve(io.cwd, values.config ?? join(root, 'cadence.yaml'));
+    // Installer les skills ou le hook ne lit pas le plan : un cadence.yaml fautif ne doit pas l'empêcher.
+    const installing = command === 'skills' || (command === 'hook' && rest[0] === 'install');
+    const planConfig = installing ? null : readPlanConfig(configPath);
+    const planPath = resolve(io.cwd, values.file ?? io.env.RAF_FILE ?? resolve(root, planConfig?.path ?? 'docs/plan/raf.yaml'));
+    const loadPlan = () => Plan.load(planPath, planConfig?.settings);
     const newsDir = resolve(io.cwd, values.dir ?? join(root, 'docs/nouveautes'));
     const need = (n, usage) => {
         if (rest.length < n)
@@ -98,6 +111,8 @@ function dispatch(argv, io) {
     };
     switch (command) {
         case 'init': {
+            if (planConfig?.settings.format)
+                throw new RafError(`plan en lecture seule : ${configPath} décrit un plan tenu par un autre outil`);
             const plan = Plan.create(planPath, values.project ?? basename(root), values.prefix ?? 'L', today);
             io.out(`plan créé : ${plan.path}`);
             if (!values['no-hook'] && gitRoot(io.cwd))
@@ -106,7 +121,7 @@ function dispatch(argv, io) {
         }
         case 'add': {
             need(1, 'add "titre"');
-            const plan = Plan.load(planPath);
+            const plan = loadPlan();
             let id;
             if (values.parent) {
                 id = plan.addTask(values.parent, rest.join(' '));
@@ -126,9 +141,11 @@ function dispatch(argv, io) {
         case 'done':
         case 'drop': {
             need(1, `${command} <id>`);
-            const plan = Plan.load(planPath);
+            const plan = loadPlan();
             const status = command === 'start' ? 'doing' : command === 'done' ? 'done' : 'dropped';
-            plan.setStatus(rest[0], status, today, { force: values.force });
+            // Le plan ne lit pas git : lui dire combien de commits du lot sa revue ne couvre pas quand elle est exigée.
+            const unreviewed = status === 'done' && plan.reviewSince && !plan.readonly && !values.force ? unreviewedWork(plan, root, rest[0]) : 0;
+            plan.setStatus(rest[0], status, today, { force: values.force, unreviewed });
             if (command === 'drop' && values.reason)
                 plan.note(rest[0], `abandonné : ${values.reason}`, today);
             plan.save();
@@ -143,28 +160,28 @@ function dispatch(argv, io) {
         }
         case 'note': {
             need(2, 'note <id> "texte"');
-            const plan = Plan.load(planPath);
+            const plan = loadPlan();
             plan.note(rest[0], rest.slice(1).join(' '), today);
             plan.save();
             return 0;
         }
-        case 'ux': {
-            need(1, 'ux enable | ux <lot> "verdict"');
-            const plan = Plan.load(planPath);
-            if (rest[0] === 'enable') {
-                const changed = plan.enableUx(today);
-                plan.save();
-                io.out(changed ? `revue UX obligatoire pour les lots visibles à partir du ${today}` : `revue UX déjà active depuis le ${plan.uxSince}`);
-                return 0;
+        case 'ux':
+        case 'review':
+            return gate(command, rest, loadPlan, root, today, io);
+        case 'commits': {
+            need(1, 'commits <lot>');
+            const plan = loadPlan();
+            const id = rest[0];
+            if (!plan.lots().some((l) => l.id === id)) {
+                throw new RafError(id.includes('/') ? `les commits se listent par lot, pas par sous-tâche : ${id}` : `lot inconnu : ${id}`);
             }
-            need(2, 'ux <lot> "verdict"');
-            plan.lot(rest[0]);
-            plan.recordUx(rest[0], rest.slice(1).join(' '), today);
-            plan.save();
+            // Une lecture : le même ensemble que « raf done » et « raf check », plan en lecture seule compris.
+            for (const c of lotWork(plan, root, id).reverse())
+                io.out(short(c));
             return 0;
         }
         case 'list': {
-            const plan = Plan.load(planPath);
+            const plan = loadPlan();
             if (values.status && !STATUSES.includes(values.status))
                 throw new RafError(`statut inconnu : ${values.status}`);
             for (const l of plan.lots().filter((l) => !values.status || l.status === values.status)) {
@@ -173,21 +190,21 @@ function dispatch(argv, io) {
             return 0;
         }
         case 'now':
-            return now(Plan.load(planPath), root, today, io);
+            return now(loadPlan(), root, newsDir, today, io);
         case 'check': {
             const idle = values.idle === undefined ? 7 : Number(values.idle);
             if (!Number.isInteger(idle) || idle < 0)
                 throw new RafError(`--idle invalide : ${values.idle}`);
-            const issues = audit(Plan.load(planPath), root, newsDir, today, { since: values.since, idle });
+            const issues = audit(loadPlan(), root, newsDir, today, { since: values.since, idle });
             for (const i of issues)
                 io.out(`✗ ${i.message}`);
             io.out(issues.length === 0 ? '✓ plan et historique cohérents' : `${issues.length} écart(s)`);
             return issues.length === 0 ? 0 : 1;
         }
         case 'gantt': {
-            const plan = Plan.load(planPath);
+            const plan = loadPlan();
             const lots = plan.lots();
-            const linked = linkCommits(lots, readCommits(root), plan.prefix);
+            const linked = linkCommits(lots, planCommits(plan, root), plan.refs);
             const stamp = io.now();
             const html = renderGantt(ganttData(plan.project, schedule(lots, linked.byLot, today), today, `${toDay(stamp)} ${stamp.toTimeString().slice(0, 5)}`));
             const out = resolve(io.cwd, values.output ?? join(dirname(planPath), 'gantt.html'));
@@ -203,22 +220,24 @@ function dispatch(argv, io) {
                 return 0;
             }
             if (rest[0] === 'post-commit')
-                return postCommit(planPath, newsDir, root, io);
+                return postCommit(existsSync(planPath) ? loadPlan : null, newsDir, root, io);
             throw new RafError('usage : raf hook install|post-commit');
         }
-        case 'session':
+        case 'session': {
             if (!gitRoot(io.cwd))
                 throw new RafError('session : à lancer dans un dépôt git');
-            return session(rest, { plan: Plan.load(planPath), root, newsDir, state: stateDir(root), shared: sharedStateDir(root), today, out: io.out }, values);
+            // « next » n'écrit que les notes : la commande du projet ne se joue qu'à la reprise et à la clôture.
+            const facts = rest[0] === 'start' || rest[0] === 'close' ? readSessionConfig(configPath)[rest[0]] : undefined;
+            return session(rest, { plan: loadPlan(), root, newsDir, state: stateDir(root), shared: sharedStateDir(root), today, out: io.out, facts }, values);
+        }
         case 'deliver': {
             if (!gitRoot(io.cwd))
                 throw new RafError('deliver : à lancer dans un dépôt git');
-            const configPath = resolve(io.cwd, values.config ?? join(root, 'cadence.yaml'));
             if (!existsSync(configPath))
                 throw new RafError(`pas de configuration de livraison : ${configPath} (voir « cadence.yaml » dans le README)`);
             const config = parseDeliverConfig(readFileSync(configPath, 'utf8'), configPath);
-            const plan = existsSync(planPath) ? Plan.load(planPath) : null;
-            const ctx = { root, state: sharedStateDir(root), plan, config, today, dryRun: !!values['dry-run'], out: io.out, err: io.err };
+            const plan = existsSync(planPath) ? loadPlan() : null;
+            const ctx = { root, state: sharedStateDir(root), plan, config, today, dryRun: !!values['dry-run'], sha: values.sha, args: rest, out: io.out, err: io.err };
             return deliver(ctx, realDeps(root));
         }
         case 'skills': {
@@ -241,11 +260,38 @@ function dispatch(argv, io) {
             return 0;
         }
         case 'news':
-            return news(rest, Plan.load(planPath), newsDir, today, values, io);
+            return news(rest, loadPlan(), newsDir, today, values, io);
         default:
             throw new RafError(`commande inconnue : ${command} (raf --help)`);
     }
 }
+const GATES = {
+    ux: { on: 'revue UX obligatoire pour les lots visibles', already: 'revue UX déjà active' },
+    review: { on: 'revue de code obligatoire pour les lots à commits', already: 'revue de code déjà active' },
+};
+/** « raf ux … » et « raf review … » ont la même forme : activer la porte, ou noter le verdict d'un lot. */
+function gate(kind, rest, loadPlan, root, today, io) {
+    if (rest.length < 1)
+        throw new RafError(`usage : raf ${kind} enable | ${kind} <lot> "verdict"`);
+    const plan = loadPlan();
+    if (rest[0] === 'enable') {
+        const changed = kind === 'ux' ? plan.enableUx(today) : plan.enableReview(today);
+        plan.save();
+        io.out(changed ? `${GATES[kind].on} à partir du ${today}` : `${GATES[kind].already} depuis le ${kind === 'ux' ? plan.uxSince : plan.reviewSince}`);
+        return 0;
+    }
+    if (rest.length < 2)
+        throw new RafError(`usage : raf ${kind} <lot> "verdict"`);
+    // Le plan refuse lui-même une sous-tâche, un verdict vide, un lot inconnu.
+    const verdict = rest.slice(1).join(' ');
+    if (kind === 'ux')
+        plan.recordUx(rest[0], verdict, today);
+    // Le verdict vaut jusqu'au dernier commit compté du lot ; un plan en lecture seule refuse sans lire git.
+    else
+        plan.recordReview(rest[0], verdict, today, plan.readonly ? null : (lotWork(plan, root, rest[0])[0]?.sha ?? null));
+    plan.save();
+    return 0;
+}
 function describe(l, commits) {
     const bits = [`${l.estimate} j`];
     if (commits)
@@ -254,9 +300,9 @@ function describe(l, commits) {
         bits.push(`sous-tâches ${l.tasks.filter((t) => t.status === 'done').length}/${l.tasks.length}`);
     return `${l.quickwin ? '⚡ ' : ''}${l.id}  ${l.title}  (${bits.join(', ')})`;
 }
-function now(plan, root, today, io) {
+function now(plan, root, newsDir, today, io) {
     const lots = plan.lots();
-    const linked = linkCommits(lots, readCommits(root), plan.prefix);
+    const linked = linkCommits(lots, planCommits(plan, root), plan.refs);
     const count = (id) => linked.byLot.get(id)?.length ?? 0;
     const { doing, ready, blocked } = nextUp(lots);
     io.out(`${plan.project} — ${today}`);
@@ -283,21 +329,20 @@ function now(plan, root, today, io) {
         for (const l of done)
             io.out(`  ${l.id}  ${l.title}  (${l.finished})`);
     }
-    const recent = exemptPlanOnly(linkCommits(lots, readCommits(root, { since: auditSince(plan) }), plan.prefix), plan, root);
-    const issues = check(lots, { ...recent, byLot: linked.byLot }, today);
+    const issues = audit(plan, root, newsDir, today);
     if (issues.length)
         io.out(`\n${issues.length} écart(s) entre le plan et l'historique — raf check`);
     return 0;
 }
-function postCommit(planPath, newsDir, root, io) {
-    if (!existsSync(planPath))
+function postCommit(load, newsDir, root, io) {
+    if (!load)
         return 0;
     try {
-        const plan = Plan.load(planPath);
+        const plan = load();
         const head = readCommits(root, { range: '-1' })[0];
         if (!head)
             return 0;
-        const refs = extractRefs(`${head.subject}\n${head.body}`, plan.prefix);
+        const refs = plan.refs(`${head.subject}\n${head.body}`);
         if (refs.length === 0) {
             const planOnly = exemptPlanOnly({ byLot: new Map(), orphans: [head], unknown: [] }, plan, root).orphans.length === 0;
             if (!planOnly && !/^Merge\b/.test(head.subject)) {
@@ -306,12 +351,13 @@ function postCommit(planPath, newsDir, root, io) {
             return 0;
         }
         const lots = new Map(plan.lots().map((l) => [l.id, l]));
+        const planning = isPlanOnly(head.sha, plan, root);
         for (const r of refs) {
             const lot = lots.get(r.lot);
             if (!lot)
                 io.err(`raf: ${r.lot} n'existe pas dans le plan`);
-            else if (lot.status === 'todo')
-                io.err(`raf: ${r.lot} est encore todo — raf start ${r.lot}`);
+            else if (lot.status === 'todo' && !planning)
+                io.err(`raf: ${r.lot} est encore todo${plan.readonly ? '' : ` — raf start ${r.lot}`}`);
             else
                 io.err(`raf: ${r.lot} (${lot.status}) ${lot.title}`);
         }
@@ -334,7 +380,15 @@ function news([sub, ...args], plan, dir, today, values, io) {
                 throw new RafError('usage : cadence news new <lot…> [--title t]');
             for (const id of args)
                 plan.lot(id);
-            io.out(newEntry(dir, args, values.title ?? plan.lot(args[0]).title, today));
+            io.out(newEntry(dir, args, values.title ?? plan.lot(args[0]).title, today, io.now()));
+            return 0;
+        }
+        case 'stamp': {
+            const stamped = stampEntries(dir, io.now());
+            for (const s of stamped)
+                io.out(`${s.file}  created: ${s.created}`);
+            if (stamped.length === 0)
+                io.out('✓ toutes les entrées ont une heure de création');
             return 0;
         }
         case 'list':
@@ -362,7 +416,7 @@ function news([sub, ...args], plan, dir, today, values, io) {
             return 0;
         }
         default:
-            throw new RafError('usage : cadence news new|list|check|build');
+            throw new RafError('usage : cadence news new|list|check|stamp|build');
     }
 }
 function session([sub, ...args], ctx, values) {

package/dist/config.js

@@ -0,0 +1,106 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { parse } from 'yaml';
+import { isDay } from './dates.js';
+import { FIELDS, RafError, STATUSES } from './plan.js';
+const KEYS = ['path', 'project', 'since', 'ignore', 'files', 'lots', 'fields', 'statuses', 'estimates'];
+const FORMAT_KEYS = ['lots', 'fields', 'statuses', 'estimates'];
+const isObject = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const list = (v) => (v == null ? [] : Array.isArray(v) ? v.map(String) : [String(v)]);
+/**
+ * Clé `plan:` de cadence.yaml : où est le plan et, s'il est tenu par un autre outil, comment le lire.
+ * Null quand le fichier ou la clé manque — le plan est alors docs/plan/raf.yaml au format de raf.
+ */
+export function readPlanConfig(file) {
+    if (!existsSync(file))
+        return null;
+    let raw;
+    try {
+        raw = parse(readFileSync(file, 'utf8'));
+    }
+    catch (e) {
+        throw new RafError(`${file} illisible : ${e.message.split('\n')[0]}`);
+    }
+    const p = raw?.plan;
+    if (p == null)
+        return null;
+    const bad = (what) => new RafError(`${file} : plan.${what}`);
+    if (typeof p === 'string' && p.trim() !== '')
+        return { path: p, settings: {} };
+    if (!isObject(p))
+        throw new RafError(`${file} : plan doit être un chemin ou un objet`);
+    for (const k of Object.keys(p))
+        if (!KEYS.includes(k))
+            throw bad(`${k} inconnu (attendu : ${KEYS.join(', ')})`);
+    const settings = {};
+    if (p.project != null)
+        settings.project = String(p.project);
+    if (p.since != null) {
+        if (!isDay(p.since))
+            throw bad(`since « ${String(p.since)} » n'est pas une date AAAA-MM-JJ`);
+        settings.since = p.since;
+    }
+    if (p.ignore != null)
+        settings.ignore = list(p.ignore);
+    if (p.files != null)
+        settings.files = list(p.files);
+    if (FORMAT_KEYS.some((k) => p[k] != null))
+        settings.format = parseFormat(p, bad);
+    if (p.path != null && String(p.path).trim() === '')
+        throw bad('path est vide');
+    return { ...(p.path != null ? { path: String(p.path) } : {}), settings };
+}
+function parseFormat(p, bad) {
+    const format = { lots: p.lots == null ? 'lots' : String(p.lots), fields: {}, statuses: {}, estimates: {} };
+    for (const key of ['fields', 'statuses', 'estimates'])
+        if (p[key] != null && !isObject(p[key]))
+            throw bad(`${key} doit être un objet`);
+    for (const [field, keys] of Object.entries((p.fields ?? {}))) {
+        if (!FIELDS.includes(field))
+            throw bad(`fields.${field} inconnu (attendu : ${FIELDS.join(', ')})`);
+        format.fields[field] = list(keys);
+    }
+    for (const [status, theirs] of Object.entries((p.statuses ?? {}))) {
+        if (!STATUSES.includes(status))
+            throw bad(`statuses.${status} inconnu (attendu : ${STATUSES.join(', ')})`);
+        for (const s of list(theirs)) {
+            if (format.statuses[s] && format.statuses[s] !== status)
+                throw bad(`statuses : « ${s} » correspond à deux statuts`);
+            format.statuses[s] = status;
+        }
+    }
+    for (const [label, days] of Object.entries((p.estimates ?? {}))) {
+        if (typeof days !== 'number' || !(days > 0))
+            throw bad(`estimates.${label} doit être un nombre de jours positif`);
+        format.estimates[label] = days;
+    }
+    return format;
+}
+/**
+ * Clé `session:` de cadence.yaml : les faits propres au projet (son script de reprise, de clôture),
+ * joués par cadence au lieu d'être remplacés.
+ */
+export function readSessionConfig(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 s = raw?.session;
+    if (s == null)
+        return {};
+    if (!isObject(s))
+        throw new RafError(`${file} : session doit être un objet { start, close }`);
+    const config = {};
+    for (const [k, v] of Object.entries(s)) {
+        if (k !== 'start' && k !== 'close')
+            throw new RafError(`${file} : session.${k} inconnu (attendu : start, close)`);
+        if (typeof v !== 'string' || !v.trim())
+            throw new RafError(`${file} : session.${k} : commande non vide attendue`);
+        config[k] = v.trim();
+    }
+    return config;
+}

package/dist/dates.js

@@ -8,6 +8,14 @@ export function toDay(date) {
     const d = String(date.getDate()).padStart(2, '0');
     return `${y}-${m}-${d}`;
 }
+/** Horodatage local à la minute, fuseau explicite : `2026-09-29T10:12+02:00`. */
+export function toStamp(date) {
+    const two = (n) => String(n).padStart(2, '0');
+    const off = -date.getTimezoneOffset();
+    const sign = off < 0 ? '-' : '+';
+    const abs = Math.abs(off);
+    return `${toDay(date)}T${two(date.getHours())}:${two(date.getMinutes())}${sign}${two(Math.floor(abs / 60))}:${two(abs % 60)}`;
+}
 function parse(day) {
     return new Date(`${day}T00:00:00Z`);
 }

package/dist/deliver.js

@@ -1,7 +1,7 @@
 import { execFileSync, spawnSync } from 'node:child_process';
 import { parse } from 'yaml';
-import { headSha, isAncestor, onRemote, readCommits, repoStatus } from './git.js';
-import { extractRefs, RafError } from './plan.js';
+import { headSha, isAncestor, onRemote, readCommits, repoStatus, resolveCommit } from './git.js';
+import { RafError } from './plan.js';
 import { appendDelivery, lastDelivery, lockAlive, lockPath, readLock, releaseLock, removeStaleLock, writeLock } from './state.js';
 const POLL_CI = 15_000;
 const CI_APPEAR = 300_000;
@@ -23,6 +23,14 @@ export function parseDeliverConfig(text, file) {
         throw new RafError(`${file} : clé deliver absente`);
     const cfg = d;
     const bad = (what) => new RafError(`${file} : deliver.${what}`);
+    let script;
+    if (cfg.script !== undefined) {
+        if (typeof cfg.script !== 'string' || !cfg.script.trim())
+            throw bad('script : commande non vide attendue');
+        if (cfg.ci !== undefined || cfg.deploy !== undefined)
+            throw bad('script remplace ci et deploy : garder l\'un ou les autres');
+        script = cfg.script.trim();
+    }
     let ci = 'none';
     if (cfg.ci === 'github' || cfg.ci === 'none')
         ci = cfg.ci;
@@ -33,6 +41,8 @@ export function parseDeliverConfig(text, file) {
     }
     else if (cfg.ci !== undefined)
         throw bad('ci : attendu github, none ou { command: "…" }');
+    if (cfg.allowDirty !== undefined && typeof cfg.allowDirty !== 'boolean')
+        throw bad('allowDirty : true ou false attendu');
     const seconds = (key, dflt) => {
         const v = cfg[key];
         if (v === undefined)
@@ -45,7 +55,8 @@ export function parseDeliverConfig(text, file) {
     if (!Array.isArray(deploy) || !deploy.every((c) => typeof c === 'string' && c.trim()))
         throw bad('deploy : liste de commandes non vides attendue');
     const verify = cfg.verify ?? [];
-    if (!Array.isArray(verify) || verify.length === 0) {
+    // Avec un script de projet, les contrôles métier sont les siens : ceux de cadence deviennent facultatifs.
+    if (!Array.isArray(verify) || (verify.length === 0 && script === undefined)) {
         throw bad('verify : au moins une vérification (une livraison se prouve par son effet)');
     }
     const checks = verify.map((v, i) => {
@@ -68,7 +79,16 @@ export function parseDeliverConfig(text, file) {
             throw bad(`${where}.contains : texte attendu`);
         return { url, ...(status === undefined ? {} : { status: status }), ...(contains === undefined ? {} : { contains }) };
     });
-    return { ci, ciTimeout: seconds('ciTimeout', 1800), deploy: deploy, verify: checks, verifyTimeout: seconds('verifyTimeout', 300), deployTimeout: seconds('deployTimeout', 1800) };
+    return {
+        ci,
+        ...(script === undefined ? {} : { script }),
+        ...(cfg.allowDirty ? { allowDirty: true } : {}),
+        ciTimeout: seconds('ciTimeout', 1800),
+        deploy: deploy,
+        verify: checks,
+        verifyTimeout: seconds('verifyTimeout', 300),
+        deployTimeout: seconds('deployTimeout', 1800),
+    };
 }
 /** Dépendances réelles : sh, gh, fetch, horloge. */
 export function realDeps(root) {
@@ -119,6 +139,10 @@ export function realDeps(root) {
 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) {
+    return /^[A-Za-z0-9_@%+=:,./-]+$/.test(arg) ? arg : `'${arg.replaceAll("'", `'\\''`)}'`;
+}
 function describeCheck(c, sha) {
     if (c.command !== undefined)
         return c.command;
@@ -131,12 +155,19 @@ export async function deliver(ctx, deps) {
         err(`deliver : ${msg}`);
         return 2;
     };
-    const sha = headSha(ctx.root);
+    const head0 = headSha(ctx.root);
+    const sha = ctx.sha === undefined ? head0 : resolveCommit(ctx.root, ctx.sha);
     if (!sha)
-        return refuse('aucun commit à livrer');
+        return refuse(ctx.sha === undefined ? 'aucun commit à livrer' : `--sha ${ctx.sha} : commit introuvable`);
+    if (ctx.args.length && config.script === undefined) {
+        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(' ');
     const repo = repoStatus(ctx.root);
-    if (repo.dirty)
+    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)`);
     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);
@@ -149,16 +180,25 @@ export async function deliver(ctx, deps) {
         if (why)
             return refuse(`ci: github exige gh authentifié — ${why}`);
     }
-    const branch = repo.branch ?? 'HEAD détachée';
-    const env = { CADENCE_SHA: sha, CADENCE_SHORT: sha.slice(0, 7), CADENCE_BRANCH: repo.branch ?? '' };
+    // Un sha choisi n'est pas forcément sur la branche courante : ne pas lui en prêter une.
+    const atHead = sha === head0;
+    const branch = atHead ? (repo.branch ?? 'HEAD détachée') : 'sha choisi, antérieur ou étranger à la tête';
+    const env = { CADENCE_SHA: sha, CADENCE_SHORT: sha.slice(0, 7), CADENCE_BRANCH: atHead ? (repo.branch ?? '') : '' };
     if (ctx.dryRun) {
         out(`Livraison de ${env.CADENCE_SHORT} (${branch}) — simulation, rien n'est exécuté`);
-        out(`  CI : ${typeof config.ci === 'string' ? config.ci : config.ci.command}${config.ci === 'none' ? '' : ` (délai ${config.ciTimeout} s)`}`);
-        out('  Déploiement :');
-        if (config.deploy.length === 0)
-            out('    (aucune commande)');
-        config.deploy.forEach((c, i) => out(`    ${i + 1}. ${c}`));
-        out(`  Vérifications (réessayées pendant ${config.verifyTimeout} s) :`);
+        if (script !== null) {
+            out(`  Script du projet : ${script}`);
+            out(`    (CI, déploiement et contrôles métier sont les siens ; délai ${config.deployTimeout} s)`);
+        }
+        else {
+            out(`  CI : ${typeof config.ci === 'string' ? config.ci : config.ci.command}${config.ci === 'none' ? '' : ` (délai ${config.ciTimeout} s)`}`);
+            out('  Déploiement :');
+            if (config.deploy.length === 0)
+                out('    (aucune commande)');
+            config.deploy.forEach((c, i) => out(`    ${i + 1}. ${c}`));
+        }
+        if (config.verify.length)
+            out(`  Vérifications (réessayées pendant ${config.verifyTimeout} s) :`);
         config.verify.forEach((c, i) => out(`    ${i + 1}. ${describeCheck(c, sha)}`));
         out(`  Variables : ${Object.entries(env).map(([k, v]) => `${k}=${v}`).join(' ')}`);
         return 0;
@@ -175,21 +215,37 @@ export async function deliver(ctx, deps) {
             return 1;
         };
         out(`Livraison de ${env.CADENCE_SHORT} (${branch})`);
-        const ci = await waitCi(ctx, deps, sha, env);
-        if (ci)
-            return fail(ci);
-        for (const [i, cmd] of config.deploy.entries()) {
-            out(`→ déploiement ${i + 1}/${config.deploy.length} : ${cmd}`);
-            const code = deps.exec(cmd, env, config.deployTimeout * 1000);
+        if (script !== null) {
+            out(`→ script du projet : ${script}`);
+            const code = deps.exec(script, env, config.deployTimeout * 1000);
             if (code !== 0)
-                return fail(`déploiement en échec (${codeText(code)}) : ${cmd}`);
+                return fail(`script de livraison en échec (${codeText(code)}) : ${script}`);
+        }
+        else {
+            const ci = await waitCi(ctx, deps, sha, env);
+            if (ci)
+                return fail(ci);
+            for (const [i, cmd] of config.deploy.entries()) {
+                out(`→ déploiement ${i + 1}/${config.deploy.length} : ${cmd}`);
+                const code = deps.exec(cmd, env, config.deployTimeout * 1000);
+                if (code !== 0)
+                    return fail(`déploiement en échec (${codeText(code)}) : ${cmd}`);
+            }
         }
         const failed = await verifyAll(ctx, deps, sha, env);
         if (failed)
             return fail(failed);
-        const delivered = deliveredLots(ctx, lastDelivery(ctx.state), sha);
-        appendDelivery(ctx.state, ctx.today, sha);
-        out(`✓ livré et vérifié : ${env.CADENCE_SHORT}`);
+        // 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;
+        const delivered = deliveredLots(ctx, lastDelivery(ctx.state), final);
+        appendDelivery(ctx.state, ctx.today, final);
+        if (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}`);
         if (delivered)
             out(delivered);
         return 0;
@@ -278,9 +334,11 @@ async function verifyAll(ctx, deps, sha, env) {
             const reason = await tryCheck(c, deps, sha, env, deadline - deps.now());
             if (reason === null)
                 break;
-            if (deps.now() >= deadline)
+            const left = deadline - deps.now();
+            if (left <= 0)
                 return `vérification en échec après ${ctx.config.verifyTimeout} s : ${label} — ${reason}`;
-            await deps.sleep(POLL_VERIFY);
+            // jamais au-delà du délai : une commande tuée « à l'échéance » peut rendre la main un rien avant elle
+            await deps.sleep(Math.min(POLL_VERIFY, left));
         }
     }
     return null;
@@ -295,11 +353,11 @@ function deliveredLots(ctx, prev, sha) {
     const known = new Set(ctx.plan.lots().map((l) => l.id));
     const ids = new Set();
     for (const c of readCommits(ctx.root, { range: `${prev}..${sha}` })) {
-        for (const r of extractRefs(`${c.subject}\n${c.body}`, ctx.plan.prefix))
+        for (const r of ctx.plan.refs(`${c.subject}\n${c.body}`))
             if (known.has(r.lot))
                 ids.add(r.lot);
     }
     if (ids.size === 0)
         return null;
-    return `livré : ${[...ids].sort((a, b) => a.localeCompare(b, undefined, { numeric: true })).join(', ')} — raf done si l'effet est celui attendu`;
+    return `livré : ${[...ids].sort((a, b) => a.localeCompare(b, undefined, { numeric: true })).join(', ')} — ${ctx.plan.readonly ? "à fermer avec l'outil du projet" : 'raf done'} si l'effet est celui attendu`;
 }