@sylad/cadence 0.2.0 → 0.6.0

package/dist/audit.js

@@ -4,10 +4,32 @@ import { changedFiles, readCommits } from './git.js';
 import { linkCommits } from './link.js';
 import { loadEntries, newsIssues } from './news.js';
 import { isOpen } from './plan.js';
-/** Un commit qui ne touche que le plan (ou la page Gantt) n'a pas besoin de citer un lot. */
+/** Le plan, sa page Gantt et les fichiers tenus avec lui (cadence.yaml : plan.files). */
+function ownFiles(plan, root) {
+    return new Set([relative(root, plan.path), relative(root, join(dirname(plan.path), 'gantt.html')), ...plan.files]);
+}
+/** Commits du dépôt sans les commits automatiques (motifs `ignore`) : ni audités ni comptés pour un lot. */
+export function planCommits(plan, root, opts = {}) {
+    const { patterns } = plan.ignore;
+    const commits = readCommits(root, opts);
+    return patterns.length ? commits.filter((c) => !patterns.some((re) => re.test(c.subject))) : commits;
+}
+/** Le commit ne touche-t-il que le plan (ou la page Gantt) ? */
+export function isPlanOnly(sha, plan, root) {
+    const own = ownFiles(plan, root);
+    const files = changedFiles(root, sha);
+    return files.length > 0 && files.every((f) => own.has(f));
+}
+/**
+ * N'ont pas besoin de citer un lot : un commit qui ne touche que le plan (ou la page Gantt), et un
+ * commit automatique dont le sujet correspond à un motif `ignore:` du plan.
+ */
 export function exemptPlanOnly(linked, plan, root) {
-    const own = new Set([relative(root, plan.path), relative(root, join(dirname(plan.path), 'gantt.html'))]);
+    const own = ownFiles(plan, root);
+    const { patterns } = plan.ignore;
     const orphans = linked.orphans.filter((c) => {
+        if (patterns.some((re) => re.test(c.subject)))
+            return false;
         const files = changedFiles(root, c.sha);
         return files.length === 0 || !files.every((f) => own.has(f));
     });
@@ -23,10 +45,58 @@ export function auditSince(plan, explicit) {
 /** Écarts entre le plan, l'historique et les Nouveautés — ce que `raf check` affiche. */
 export function audit(plan, root, newsDir, today, opts = {}) {
     const lots = plan.lots();
-    const linked = exemptPlanOnly(linkCommits(lots, readCommits(root, { since: auditSince(plan, opts.since) }), plan.prefix), plan, root);
+    const linked = exemptPlanOnly(linkCommits(lots, planCommits(plan, root, { since: auditSince(plan, opts.since) }), plan.refs), plan, root);
     // L'inactivité se mesure sur tout l'historique, pas seulement la fenêtre --since.
-    const all = linkCommits(lots, readCommits(root), plan.prefix);
-    return [...check(lots, { ...linked, byLot: all.byLot }, today, opts.idle ?? 7), ...newsIssues(lots, loadEntries(newsDir), newsDir), ...uxIssues(plan)];
+    const all = linkCommits(lots, planCommits(plan, root), plan.refs);
+    // Planifier un lot (commit qui ne touche que le plan) n'est pas y travailler : un lot « todo »
+    // cité seulement par de tels commits n'a pas à être démarré. Ni par des commits antérieurs à
+    // l'adoption du plan : citer un identifiant n'engageait alors à rien.
+    for (const l of lots) {
+        const cs = all.byLot.get(l.id);
+        if (l.status === 'todo' && cs)
+            all.byLot.set(l.id, workCommits(plan, root, cs));
+    }
+    // Un plan en lecture seule ne reçoit aucun verdict de raf : les deux portes n'y valent pas, même si
+    // uxSince ou reviewSince y sont écrits à la main — l'écart ne pourrait jamais être levé.
+    const gates = plan.readonly ? [] : [...uxIssues(plan), ...reviewIssues(plan, root, all.byLot)];
+    const issues = [...check(lots, { ...linked, byLot: all.byLot }, today, opts.idle ?? 7), ...newsIssues(lots, loadEntries(newsDir), newsDir), ...gates,
+        ...plan.ignore.invalid.map((src) => ({ message: `ignore : motif invalide « ${src} »` }))];
+    // Un plan en lecture seule se corrige avec l'outil du projet : ne pas conseiller une commande raf qui refuserait.
+    return plan.readonly ? issues.map((i) => ({ ...i, message: i.message.replace(/ — raf start .*$/, '') })) : issues;
+}
+/** Commits qui portent du travail sur un lot : ni antérieurs à l'adoption du plan, ni réduits au plan. */
+function workCommits(plan, root, commits) {
+    const adopted = plan.since;
+    return commits.filter((c) => (!adopted || c.day >= adopted) && !isPlanOnly(c.sha, plan, root));
+}
+/** Commits liés à un lot, du plus récent au plus ancien, avant tout tri : commits de plan et d'avant l'adoption compris. */
+function lotCommits(plan, root, lotId) {
+    return linkCommits(plan.lots(), planCommits(plan, root), plan.refs).byLot.get(lotId) ?? [];
+}
+/** Commits à relire d'un lot, du plus récent au plus ancien — ce que compte la porte de revue de code et que liste `raf commits`. */
+export function lotWork(plan, root, lotId) {
+    return workCommits(plan, root, lotCommits(plan, root, lotId));
+}
+/**
+ * Commits à relire que la revue de code d'un lot ne couvre pas, parmi ses commits liés (du plus récent
+ * au plus ancien) : tous sans verdict ; aucun pour un verdict qui ne dit pas quel commit il a relu
+ * (écrit à la main) ; sinon ceux qui suivent le commit relu — tous quand il n'y en avait aucun, ou
+ * quand il n'est plus parmi ceux du lot (historique réécrit) : la revue ne se rattache alors à rien.
+ */
+function unreviewed(plan, root, review, linked) {
+    if (!review)
+        return workCommits(plan, root, linked);
+    const reviewed = review.commit;
+    if (reviewed === undefined)
+        return [];
+    const at = reviewed === null ? -1 : linked.findIndex((c) => c.sha === reviewed);
+    // Seuls les commits postérieurs sont examinés : un lot relu à son dernier commit ne coûte aucun appel git.
+    return workCommits(plan, root, at < 0 ? linked : linked.slice(0, at));
+}
+/** Nombre de commits d'un lot que sa revue de code ne couvre pas — ce que `raf done` refuse quand la porte est active. */
+export function unreviewedWork(plan, root, lotId) {
+    const lot = plan.lots().find((l) => l.id === lotId);
+    return lot ? unreviewed(plan, root, lot.review, lotCommits(plan, root, lotId)).length : 0;
 }
 /**
  * Lots visibles terminés APRÈS le jour d'activation sans revue UX enregistrée. Le jour même est exclu :
@@ -42,6 +112,26 @@ export function uxIssues(plan) {
         .filter((l) => l.visible && l.status === 'done' && !l.ux && (!l.finished || l.finished > since))
         .map((l) => ({ message: `${l.id} est visible et terminé sans revue UX — raf ux ${l.id} "verdict"` }));
 }
+/**
+ * Lots terminés APRÈS le jour d'activation avec des commits à relire que leur revue de code ne couvre
+ * pas : aucun verdict, ou un verdict antérieur à ces commits. Même règle de date que `uxIssues` ; un
+ * lot sans commit n'a rien à faire relire.
+ */
+export function reviewIssues(plan, root, byLot) {
+    const since = plan.reviewSince;
+    if (!since)
+        return [];
+    return plan
+        .lots()
+        .filter((l) => l.status === 'done' && (!l.finished || l.finished > since))
+        .map((l) => ({ id: l.id, reviewed: !!l.review, commits: unreviewed(plan, root, l.review, byLot.get(l.id) ?? []).length }))
+        .filter((l) => l.commits > 0)
+        .map((l) => ({
+        message: l.reviewed
+            ? `${l.id} est terminé avec ${l.commits} commit(s) postérieur(s) à sa revue de code, à refaire — raf review ${l.id} "verdict"`
+            : `${l.id} est terminé avec ${l.commits} commit(s) sans revue de code — raf review ${l.id} "verdict"`,
+    }));
+}
 /** Ce qui vient ensuite : lots en cours, puis lots prêts (dépendances closes), gains rapides d'abord. */
 export function nextUp(lots) {
     const byId = new Map(lots.map((l) => [l.id, l]));

package/dist/check.js

@@ -1,6 +1,7 @@
 import { diffDays } from './dates.js';
 import { isOpen } from './plan.js';
-const short = (c) => `${c.sha.slice(0, 7)} ${c.subject}`;
+/** Un commit sur une ligne : sha abrégé et sujet. */
+export const short = (c) => `${c.sha.slice(0, 7)} ${c.subject}`;
 export function check(lots, linked, today, idleDays = 7) {
     const issues = [];
     const ids = new Set(lots.map((l) => l.id));

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`);
 }