@sylad/cadence 1.41.0 → 1.42.1

package/dist/cli/lead-commands.js

@@ -0,0 +1,161 @@
+// Les commandes du lead : lead tour|priority|hold|release, config set (L488, sorti de cli.ts).
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { gitRoot } from '../git.js';
+import { RafError } from '../plan.js';
+import { configSet } from '../config-set.js';
+import { movePriority } from '../priority.js';
+import { findProjects, isProject, leadTour, readDepth, readLeadUx, tourFreeLine, tourLine, tourNoTestLines, tourWorktreeLines } from '../lead.js';
+import { tourMemoryLines } from '../memory-index.js';
+import { localOverdueLines } from '../local-task.js';
+import { configuredCap, expiredHoldLines, slotsLine } from '../orchestrate/command.js';
+import { addHold, cadenceHome, releaseHold } from '../orchestrate/registry.js';
+import { perfHeader } from '../perf.js';
+import { readPerf } from './stats-commands.js';
+/** Les racines git des projets du tour (la clé `depth:` du dossier, un seul niveau si elle est illisible : le tour a déjà sa ligne d'erreur). */
+function tourRoots(parent, depth) {
+    let levels = depth;
+    if (levels === undefined) {
+        try {
+            levels = readDepth(parent);
+        }
+        catch {
+            levels = 1;
+        }
+    }
+    const dirs = findProjects(parent, levels);
+    return (dirs.length === 0 && isProject(parent) ? [parent] : dirs).map((d) => gitRoot(d) ?? d);
+}
+/** Durée par défaut (minutes) d'une session du lead inscrite par `lead hold` : de quoi finir un correctif ou une revue, pas de quoi oublier la réservation toute la journée. */
+const HOLD_TTL_MINUTES = 60;
+/** Longueur maximale de l'étiquette encodée : un nom de fichier tient en 255 octets, `.json.tmp` en prend 9. */
+const HOLD_LABEL_MAX = 200;
+/** `cadence lead priority <projet> --before|--after <projet> [dossier]` (L449) : range un projet dans la liste `priority:` du cadence.yaml du dossier (celui du tour), sans modèle ni commit. */
+function leadPriority(rest, before, after, depth, io) {
+    const usage = 'usage : cadence lead priority <projet> --before|--after <projet> [dossier] [--depth n]';
+    if (rest.length < 2 || rest.length > 3 || (before === undefined) === (after === undefined))
+        throw new RafError(usage);
+    const place = before !== undefined ? 'before' : 'after';
+    const levels = depth === undefined ? undefined : Number(depth);
+    if (levels !== undefined && !(Number.isInteger(levels) && levels >= 1))
+        throw new RafError(`--depth invalide : ${depth} (un entier ≥ 1)`);
+    const parent = resolve(io.cwd, rest[2] ?? '.');
+    if (!existsSync(parent))
+        throw new RafError(`lead priority : dossier introuvable : ${parent}`);
+    const target = (before ?? after);
+    const moved = movePriority(parent, rest[1], place, target, levels);
+    io.out(moved.changed ? `${rest[1]} placé ${place === 'before' ? 'avant' : 'après'} ${target} dans priority: de ${join(parent, 'cadence.yaml')} (ordre : ${moved.order.join(' > ')}) — le fichier est modifié, à commiter` : `${rest[1]} est déjà ${place === 'before' ? 'avant' : 'après'} ${target} : rien à changer`);
+    return 0;
+}
+/** `cadence lead hold <étiquette> [--ttl minutes]` / `lead release <étiquette>` (L255) : inscrit, ou rend, une session lancée à la main par le lead, qui compte dans les créneaux libres. */
+function leadHold(rest, ttl, io, today) {
+    const [verb, label] = rest;
+    const usage = verb === 'hold' ? 'usage : cadence lead hold <étiquette> [--ttl minutes]' : 'usage : cadence lead release <étiquette>';
+    if (rest.length !== 2 || !label.trim())
+        throw new RafError(usage);
+    if (verb === 'release') {
+        if (ttl !== undefined)
+            throw new RafError(`--ttl ne va qu'avec lead hold (${usage})`);
+        io.out(releaseHold(cadenceHome(), label) ? `session « ${label} » rendue` : `aucune session « ${label} » inscrite`);
+        // ce que la libération laisse (L416) : les créneaux, les lots prêts qui peuvent les prendre, et un ⚠ tant qu'un créneau reste vide
+        const { line, free } = slotsLine(configuredCap(io.env), io.now());
+        io.out(line);
+        const ready = tourFreeLine(leadTour(resolve(io.cwd), today));
+        if (ready)
+            io.out(ready);
+        if (free > 0)
+            io.out(`⚠ ${free} ${free === 1 ? 'créneau libre' : 'créneaux libres'} sur ${configuredCap(io.env)} : lancer un lot prêt ou une session, un créneau vide ne sert à rien`);
+        return 0;
+    }
+    // le nom de fichier encode l'étiquette (6 octets par lettre accentuée) : au-delà, le système de fichiers refuse (ENAMETOOLONG)
+    if (encodeURIComponent(label).length > HOLD_LABEL_MAX)
+        throw new RafError(`étiquette trop longue (${usage})`);
+    const minutes = ttl === undefined ? HOLD_TTL_MINUTES : Number(ttl);
+    if (!(Number.isInteger(minutes) && minutes >= 1))
+        throw new RafError(`--ttl invalide : ${ttl} (un nombre entier de minutes ≥ 1)`);
+    addHold(cadenceHome(), label, minutes, io.now());
+    io.out(`session « ${label} » inscrite pour ${minutes} min : elle compte dans les créneaux libres (cadence lead release « ${label} » à sa fin)`);
+    return 0;
+}
+/** Poser une clé dans le cadence.yaml de chaque projet du dossier (L342) : ne lit ni le plan ni le cadence.yaml du dossier courant. */
+export function cmdConfig(c) {
+    const { rest, values, io, today } = c;
+    if (rest[0] !== 'set' || rest.length !== 3)
+        throw new RafError('usage : cadence config set <clé> <valeur> --all [--dry-run] [--depth n]');
+    if (!values.all)
+        throw new RafError('config set demande --all : la commande s\'applique aux projets du dossier courant (lancer la commande dans le projet visé pour un seul)');
+    if (values.depth !== undefined && !(Number.isInteger(Number(values.depth)) && Number(values.depth) >= 1))
+        throw new RafError(`--depth invalide : ${values.depth} (un entier ≥ 1)`);
+    const parent = resolve(io.cwd);
+    const result = configSet(parent, rest[1], rest[2], { dryRun: values['dry-run'], depth: values.depth === undefined ? readDepth(parent) : Number(values.depth) }, today);
+    for (const l of result.lines)
+        io.out(l);
+    return result.code;
+}
+/** cadence lead tour|priority|hold|release. Le tour parcourt les sous-dossiers (ou, sans sous-projet, prend le dossier lui-même s'il est un projet) : il ne lit pas le plan du dossier courant. */
+export function cmdLead(c) {
+    const { rest, values, io, today } = c;
+    if (rest[0] === 'hold' || rest[0] === 'release')
+        return leadHold(rest, values.ttl, io, today);
+    if (rest[0] === 'priority')
+        return leadPriority(rest, values.before, values.after, values.depth, io);
+    if (values.ttl !== undefined)
+        throw new RafError('--ttl ne va qu\'avec lead hold');
+    if (rest[0] !== 'tour' || rest.length > 2)
+        throw new RafError('usage : cadence lead tour [dossier] [--idle 3] [--depth n] [--json] | lead priority <projet> --before|--after <projet> [dossier] | lead hold <étiquette> [--ttl minutes] | lead release <étiquette>');
+    const idle = values.idle === undefined ? undefined : Number(values.idle);
+    if (idle !== undefined && !(Number.isInteger(idle) && idle >= 0))
+        throw new RafError(`--idle invalide : ${values.idle}`);
+    const depth = values.depth === undefined ? undefined : Number(values.depth);
+    if (depth !== undefined && !(Number.isInteger(depth) && depth >= 1))
+        throw new RafError(`--depth invalide : ${values.depth} (un entier ≥ 1)`);
+    const parent = resolve(io.cwd, rest[1] ?? '.');
+    if (!existsSync(parent))
+        throw new RafError(`lead tour : dossier introuvable : ${parent}`);
+    const rows = leadTour(parent, today, idle, depth);
+    if (values.json)
+        io.out(JSON.stringify(rows, null, 2));
+    else if (rows.length === 0)
+        io.out(`aucun projet sous ${parent} (.cadence/raf.yaml, docs/plan/raf.yaml ou cadence.yaml avec plan:)`);
+    else {
+        // L'en-tête perf (L227) : un ⚠ par ligne avant les projets ; un dossier que perf ne lit pas n'en donne pas, et ses avertissements ne sont pas repris.
+        try {
+            for (const l of perfHeader(readPerf(parent, today, undefined, () => { })))
+                io.out(l);
+        }
+        catch {
+            // pas de .cadence/runs, grille de prix mal formée, journaux ou plans illisibles : le tour ne change pas
+        }
+        for (const r of rows)
+            io.out(tourLine(r));
+        // les worktrees de lot que des vagues ont conservés : aucun n'est oublié en silence (L279, R19)
+        // … puis l'index MEMORY.md du dossier, s'il pèse trop (L442) : le lead propose le regroupement, rien n'est écrit
+        for (const l of [...tourWorktreeLines(rows, io.now().getTime()), ...tourMemoryLines(io.env, parent)])
+            io.out(l);
+        // un projet sans orchestrate.test : la vague ne lancera pas la suite (L327)
+        for (const l of tourNoTestLines(rows))
+            io.out(l);
+        // les créneaux libres viennent du registre, le lead les lit au lieu de les calculer (L141)
+        // toujours imprimés, même sans vague ni session du lead (L416) : un créneau vide se lit, il ne se déduit pas d'une ligne absente
+        io.out(slotsLine(configuredCap(io.env), io.now()).line);
+        // en face des créneaux libres, les lots prêts dont aucune ressource n'est prise (L252)
+        const free = tourFreeLine(rows);
+        if (free)
+            io.out(free);
+        // une session du lead dont le TTL est échu (L278) : rien ne l'arrête, le tour la signale (hors --json, comme les créneaux)
+        // … et une tâche locale (L519) au-delà de son délai : le dépôt reste verrouillé, le tour le dit au lieu de le libérer en silence
+        for (const l of [...expiredHoldLines(io.now()), ...localOverdueLines(tourRoots(parent, depth), io.now())])
+            io.out(l);
+        // le réglage lead.ux du cadence.yaml du dossier (L197) : le lead lit ici qui pose le verdict UX, au lieu d'ouvrir le fichier
+        try {
+            if (readLeadUx(parent) === 'lead')
+                io.out('verdict UX : lead (le lead pose raf ux d\'après le rapport du ux-reviewer et les captures ; l\'humain n\'est consulté qu\'en cas de doute)');
+        }
+        catch (e) {
+            // un cadence.yaml illisible a déjà sa ligne d'erreur en tête de tour
+            if (/lead\.ux/.test(e.message))
+                io.out(`cadence.yaml · ✗ erreur : ${e.message.replace(/^.*cadence\.yaml : /, '')}`);
+        }
+    }
+    return 0;
+}

package/dist/cli/lot-commands.js

@@ -0,0 +1,257 @@
+// Les commandes qui écrivent le plan, un lot à la fois (L488, sorti de cli.ts).
+import { relative, resolve } from 'node:path';
+import { refuseRedAcceptation } from '../raf-close-checks.js';
+import { statusCommand } from '../raf-status.js';
+import { PLAN_LEGACY } from '../config.js';
+import { audit, isNonConformingVerdict, lotWork, planCommits, unreviewedWork } from '../audit.js';
+import { short } from '../check.js';
+import { isDay } from '../dates.js';
+import { PLAN_ACTIONS } from '../plan-commit.js';
+import { printUncommittedPlan } from '../plan-uncommitted.js';
+import { resolveCommit } from '../git.js';
+import { loadEntries } from '../news.js';
+import { addLot } from '../cli-add.js';
+import { RafError, SCREENS } from '../plan.js';
+import { warnIntegrating, warnWaveWorking, waveHolding } from '../repo-busy.js';
+import { knownLot, touchedLot } from './context.js';
+/** raf add "titre" : ajoute un lot ou une sous-tâche. */
+export function cmdAdd(c) {
+    const { rest, values, io, today, root, loadPlan, refuseLongTitle, need } = c;
+    need(1, 'add "titre"');
+    const plan = loadPlan();
+    const id = addLot(plan, values, rest.join(' '), today, refuseLongTitle);
+    plan.save();
+    io.out(id);
+    warnIntegrating(root, io.err);
+    warnWaveWorking(root, io.env, io.err);
+    return 0;
+}
+/** raf start|done|drop <id> : pose le statut du lot, sous les refus de la porte de revue, de l'acceptation et du titre public. */
+export function cmdSetStatus(c) {
+    const { rest, values, io, today, root, configPath, planConfig, loadPlan, newsDir, refuseLongTitle, need, command } = c;
+    need(1, `${command} <id>`);
+    const plan = loadPlan();
+    const status = command === 'start' ? 'doing' : command === 'done' ? 'done' : 'dropped';
+    // Le titre public part au site : un titre au-delà de la limite déclarée y ferait échouer le build.
+    if (status === 'done' && !rest[0].includes('/')) {
+        const lot = plan.lots().find((l) => l.id === rest[0]);
+        // Sans public: d'un lot visible, le site reprend le titre de sa Nouveauté la plus récente.
+        const pub = lot?.public ?? (lot?.visible ? loadEntries(newsDir).find((e) => e.lots.includes(lot.id))?.title : undefined);
+        if (pub)
+            refuseLongTitle(pub, lot?.public ? '' : ' — titre de la Nouveauté reprise par le site : corriger l\'entrée ou poser raf public');
+    }
+    // Le plan ne lit pas git : lui dire combien de commits du lot sa revue ne couvre pas quand elle est exigée.
+    if (status === 'done' && !rest[0].includes('/'))
+        refuseRedAcceptation(root, configPath, rest[0], !!values.force, io.err);
+    const unreviewed = status === 'done' && plan.reviewSince && !plan.readonly && !values.force ? unreviewedWork(plan, root, rest[0]) : 0;
+    const verdict = status === 'done' && !rest[0].includes('/') ? plan.lots().find((l) => l.id === rest[0])?.review?.verdict : undefined;
+    const nonConforming = verdict !== undefined && isNonConformingVerdict(verdict);
+    plan.setStatus(rest[0], status, today, { force: values.force, unreviewed, nonConforming });
+    if (command === 'drop' && values.reason)
+        plan.note(rest[0], `abandonné : ${values.reason}`, today);
+    plan.save();
+    io.out(`${rest[0]} → ${status}`);
+    if (status === 'done') {
+        warnIntegrating(root, io.err);
+        warnWaveWorking(root, io.env, io.err);
+    }
+    touchedLot(plan, rest[0], values.verbose, io);
+    if (status === 'done' && !rest[0].includes('/')) {
+        const lot = plan.lot(rest[0]);
+        if (lot.visible && !loadEntries(newsDir).some((e) => e.lots.includes(lot.id))) {
+            io.out(`${lot.id} est visible : écrire l'entrée : cadence news new ${lot.id}`);
+        }
+        printUncommittedPlan(io.out, plan, root, lot.id, planConfig?.commit);
+    }
+    return 0;
+}
+/** raf archive : déplace les lots clos vers .cadence/archive/. */
+export function cmdArchive(c) {
+    const { values, io, today, root, planConfig, planPath, loadPlan, newsDir } = c;
+    if (values.before !== undefined && !isDay(values.before))
+        throw new RafError(`--before invalide : ${values.before} (attendu AAAA-MM-JJ)`);
+    // L'archive vit à côté du plan : à l'ancien emplacement, elle irait sous docs/ (publié) et raf migrate ne la déplacerait pas — migrer d'abord.
+    if (planPath === resolve(root, PLAN_LEGACY))
+        throw new RafError(`raf archive refusé : le plan est à l'ancien emplacement ${PLAN_LEGACY}, l'archive irait sous docs/ — le déplacer d'abord : raf migrate`);
+    const dry = !!values['dry-run'];
+    const plan = loadPlan();
+    // Un lot clos qui a encore un écart (revue, UX, docs.sync, Nouveauté… ce que `raf check` signale) reste dans le plan, avec l'écart pour raison.
+    const issues = audit(plan, root, newsDir, today);
+    const blocked = (lot) => issues.find((i) => plan.refs(i.message).some((r) => r.lot === lot.id))?.message ?? null;
+    const { moved, kept } = plan.archive(today, { before: values.before, dryRun: dry, blocked: (lot) => (blocked(lot) ? `écart ouvert — ${blocked(lot)}` : null) });
+    const files = [...new Set(moved.map((m) => m.file))];
+    for (const f of files) {
+        const ids = moved.filter((m) => m.file === f).map((m) => m.lot.id);
+        io.out(`${dry ? 'à archiver' : 'archivé'} dans ${relative(io.cwd, f)} : ${ids.join(', ')}`);
+    }
+    for (const k of kept)
+        io.out(`${k.id} reste dans le plan : ${k.why}`);
+    if (moved.length === 0)
+        io.out('rien à archiver');
+    else if (!dry) {
+        if (plan.republishes)
+            io.err('raf: plan.onWrite republie le fichier du plan sans les lots archivés : le générateur de la copie publiée doit aussi lire .cadence/archive/*.yaml (clé `lots`), sinon l\'historique livré disparaît de la feuille de route publique');
+        printUncommittedPlan(io.out, plan, root, moved[0].lot.id, planConfig?.commit, PLAN_ACTIONS.archived(moved.length));
+    }
+    return 0;
+}
+/** raf todo <id> : remet en attente un lot démarré sans commit de travail, ou rouvre un lot clos. */
+export function cmdTodo(c) {
+    const { rest, values, io, today, root, loadPlan, need } = c;
+    need(1, 'todo <id> [--reason texte]');
+    const plan = loadPlan();
+    plan.putBack(rest[0], today, values.reason ?? '', () => lotWork(plan, root, rest[0]).length);
+    plan.save();
+    io.out(`${rest[0]} → todo`);
+    return 0;
+}
+/** raf note <id> "texte". */
+export function cmdNote(c) {
+    const { rest, values, io, today, root, loadPlan, need } = c;
+    need(2, 'note <id> "texte"');
+    const plan = loadPlan();
+    plan.note(rest[0], rest.slice(1).join(' '), today);
+    plan.save();
+    warnIntegrating(root, io.err);
+    warnWaveWorking(root, io.env, io.err);
+    touchedLot(plan, rest[0], values.verbose, io);
+    return 0;
+}
+/** raf did <id> : un lot récurrent a été refait. */
+export function cmdDid(c) {
+    const { rest, io, today, loadPlan, need } = c;
+    need(1, 'did <id> ["texte"]');
+    const plan = loadPlan();
+    plan.did(rest[0], today, rest.slice(1).join(' '));
+    plan.save();
+    io.out(`${rest[0]} refait le ${today}`);
+    return 0;
+}
+/** raf title <id> "titre" : remplace le titre d'un lot. */
+export function cmdTitle(c) {
+    const { rest, today, loadPlan, need } = c;
+    need(2, 'title <id> "nouveau titre"');
+    const plan = loadPlan();
+    plan.setTitle(rest[0], rest.slice(1).join(' '), today);
+    plan.save();
+    return 0;
+}
+/** raf uses <lot> [<ressource>…] : remplace les ressources partagées du lot. */
+export function cmdUses(c) {
+    const { rest, loadPlan, need } = c;
+    need(1, 'uses <lot> [<ressource>…]');
+    const plan = loadPlan();
+    plan.setUses(rest[0], rest.slice(1));
+    plan.save();
+    return 0;
+}
+/** raf move <id> --before|--after <id> : réordonne un lot dans le plan. */
+export function cmdMove(c) {
+    const { rest, values, io, root, loadPlan } = c;
+    // Une seule position : --before ou --after, avec une cible (« after » est aussi le drapeau de « add », « before » celui de « archive »).
+    const place = values.before !== undefined && values.after === undefined ? 'before' : values.after !== undefined && values.before === undefined ? 'after' : null;
+    if (rest.length !== 1 || !place)
+        throw new RafError('usage : raf move <id> --before <id> | raf move <id> --after <id>');
+    const plan = loadPlan();
+    plan.move(rest[0], place, values[place]); // en mémoire : les refus de la commande (plan en lecture seule, parent, archive) passent avant celui de la vague
+    // Un lot de la vague s'appuie sur l'ordre du plan qu'il a lu : le réordonner sous ses pieds est refusé tant que la vague tient le dépôt.
+    const holding = waveHolding(root, 'move');
+    if (holding)
+        throw new RafError(`move : orchestration en cours (vague ${holding.wave}, pid ${holding.pid}) — attendre que les lots de ce dépôt soient finis (le verrou tombe dès que tous sont prêts ou rendus), puis relancer`);
+    plan.save();
+    touchedLot(plan, rest[0], values.verbose, io);
+    return 0;
+}
+/** raf public <id> "titre public" | --clear. */
+export function cmdPublic(c) {
+    const { rest, values, io, loadPlan, refuseLongTitle, need } = c;
+    need(values.clear ? 1 : 2, 'public <id> "titre public" | public <id> --clear');
+    if (values.clear && rest.length > 1)
+        throw new RafError('--clear n\'attend pas de titre');
+    const plan = loadPlan();
+    if (!values.clear)
+        refuseLongTitle(rest.slice(1).join(' '));
+    plan.setPublic(rest[0], values.clear ? null : rest.slice(1).join(' '));
+    plan.save();
+    touchedLot(plan, rest[0], values.verbose, io);
+    return 0;
+}
+/** raf screen <id> page|component|journey|none. */
+export function cmdScreen(c) {
+    const { rest, loadPlan, need } = c;
+    need(2, 'screen <id> page|component|journey|none');
+    if (rest.length > 2)
+        throw new RafError('usage : raf screen <id> page|component|journey|none');
+    const plan = loadPlan();
+    if (rest[1] !== 'none' && !SCREENS.includes(rest[1]))
+        throw new RafError(`screen inconnu : ${rest[1]} (${SCREENS.join(', ')}, none)`);
+    plan.setScreen(rest[0], rest[1] === 'none' ? null : rest[1]);
+    plan.save();
+    return 0;
+}
+/** raf estimate <id> <jours>. */
+export function cmdEstimate(c) {
+    const { rest, loadPlan } = c;
+    if (rest.length !== 2)
+        throw new RafError('usage : raf estimate <id> <jours>');
+    const plan = loadPlan();
+    if (!/^\d+(\.\d+)?$/.test(rest[1].trim()))
+        throw new RafError(`estimation invalide : ${rest[1]} (un nombre de jours > 0)`);
+    plan.setEstimate(rest[0], Number(rest[1]));
+    plan.save();
+    return 0;
+}
+/** raf visible <id> on|off. */
+export function cmdVisible(c) {
+    const { rest, loadPlan } = c;
+    if (rest.length !== 2 || (rest[1] !== 'on' && rest[1] !== 'off'))
+        throw new RafError('usage : raf visible <id> on|off');
+    const plan = loadPlan();
+    plan.setVisible(rest[0], rest[1] === 'on');
+    plan.save();
+    return 0;
+}
+/** raf ignore <sha> | "<sujet exact>" : acquitte un commit sans lot. */
+export function cmdIgnore(c) {
+    const { rest, values, io, today, root, loadPlan, need } = c;
+    need(1, 'ignore <sha> | "<sujet exact>" [--reason texte]');
+    if (rest.length > 1)
+        throw new RafError('un seul commit attendu ; la raison se passe par --reason "texte"');
+    const plan = loadPlan();
+    const arg = rest[0];
+    const commits = planCommits(plan, root);
+    // Un sujet exact l'emporte sur un nom de ref homonyme (`other` à la fois sujet et branche).
+    const sha = commits.some((c) => c.subject === arg) ? null : resolveCommit(root, arg);
+    const found = sha ? commits.find((c) => c.sha === sha) : commits.find((c) => c.subject === arg);
+    if (!found)
+        throw new RafError(`aucun commit ne correspond à « ${arg} » (sha ou sujet exact)`);
+    // Un sha est exact ; un sujet vaut pour tous les commits qui le portent.
+    const bySha = sha !== null;
+    plan.acknowledge({ ...(bySha ? { sha: found.sha, subject: found.subject } : { subject: found.subject }), date: today, ...(values.reason ? { reason: values.reason } : {}) });
+    plan.save();
+    io.out(`${bySha ? short(found) : found.subject} acquitté`);
+    return 0;
+}
+/** raf docs-ok <lot> --reason texte : acquitte l'écart docs.sync d'un lot. */
+export function cmdDocsOk(c) {
+    const { rest, values, io, today, loadPlan, need } = c;
+    need(1, 'docs-ok <lot> --reason texte');
+    if (rest.length > 1)
+        throw new RafError('un seul lot attendu ; la raison se passe par --reason "texte"');
+    const plan = loadPlan();
+    knownLot(plan, rest[0], 'docs-ok se pose sur un lot, pas sur une sous-tâche');
+    plan.setDocsOk(rest[0], values.reason ?? '', today);
+    // Un plan en lecture seule n'est pas écrit : l'acquittement est dans .cadence/docs-ok.yaml, à commiter à la place du plan (L386).
+    if (plan.readonly)
+        io.out(`${rest[0]} : écart docs.sync acquitté dans .cadence/docs-ok.yaml (le plan n'est pas touché) — commiter ce fichier`);
+    else {
+        plan.save();
+        io.out(`${rest[0]} : écart docs.sync acquitté`);
+    }
+    return 0;
+}
+/** raf status : les états détaillés du projet, ou la pose de l'état d'un lot. */
+export function cmdStatus(c) {
+    const { rest, values, io, today, root, loadPlan } = c;
+    return statusCommand(loadPlan(), rest, { back: !!values.back, today, out: io.out, commits: (p, id) => lotWork(p, root, id).length });
+}

package/dist/cli/read-commands.js

@@ -0,0 +1,227 @@
+// Les commandes qui lisent le plan et l'historique : commits, show, list, now, check, gantt, news (L488, sorti de cli.ts).
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { readOrchestrateConfig } from '../config.js';
+import { repoSections } from '../repos.js';
+import { lotJson, lotLines } from '../lot-lines.js';
+import { audit, gateWaiting, hypothesesOf, lotWork, nextUp, planCommits, workByLot } from '../audit.js';
+import { short } from '../check.js';
+import { toDay } from '../dates.js';
+import { ganttData, renderGantt } from '../gantt.js';
+import { linkCommits } from '../link.js';
+import { buildNews, loadEntries, newEntry, newsData, newsIssues, stampEntries } from '../news.js';
+import { RafError, STATUSES } from '../plan.js';
+import { dueLine, recurringByDue } from '../recurring.js';
+import { schedule } from '../schedule.js';
+import { coverageCommand } from '../ref/coverage.js';
+import { knownLot } from './context.js';
+function describe(l, commits) {
+    const bits = [`${l.estimate} j`];
+    if (commits)
+        bits.push(`${commits} commit(s)`);
+    if (l.tasks.length)
+        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, newsDir, today, io) {
+    const lots = plan.lots();
+    const linked = linkCommits(lots, planCommits(plan, root), plan.refs);
+    const { doing, ready, blocked } = nextUp(lots);
+    const work = workByLot(plan, root, linked, [...doing, ...ready.slice(0, 5)].map((l) => l.id));
+    const count = (id) => work.get(id)?.length ?? 0;
+    io.out(`${plan.project} — ${today}`);
+    io.out('\nEn cours');
+    if (doing.length === 0)
+        io.out('  (rien)');
+    for (const l of doing)
+        io.out(`  ${describe(l, count(l.id))}`);
+    io.out('\nÀ suivre');
+    if (ready.length === 0)
+        io.out('  (rien de prêt)');
+    for (const l of ready.slice(0, 5))
+        io.out(`  ${describe(l, count(l.id))}`);
+    if (ready.length > 5)
+        io.out(`  … et ${ready.length - 5} autre(s)`);
+    const gated = gateWaiting(lots, blocked);
+    const byDeps = blocked.filter((l) => !gated.some((g) => g.lot === l));
+    if (byDeps.length)
+        io.out(`  en attente de dépendances : ${byDeps.map((l) => l.id).join(', ')}`);
+    if (gated.length)
+        io.out(`  en attente de condition de tirage : ${gated.map((g) => `${g.lot.id} (${g.text})`).join(', ')}`);
+    const recurring = recurringByDue(lots, today);
+    if (recurring.length) {
+        io.out('\nRécurrent');
+        for (const l of recurring)
+            io.out(`  ${l.id}  ${l.title}  (tous les ${l.every} j, ${dueLine(l, today)})`);
+    }
+    const done = lots
+        .filter((l) => l.status === 'done' && l.finished)
+        .sort((a, b) => (b.finished > a.finished ? 1 : -1))
+        .slice(0, 3);
+    if (done.length) {
+        io.out('\nTerminés récemment');
+        for (const l of done)
+            io.out(`  ${l.id}  ${l.title}  (${l.finished})`);
+    }
+    const issues = audit(plan, root, newsDir, today).filter((i) => !i.warning);
+    if (issues.length)
+        io.out(`\n${issues.length} écart(s) entre le plan et l'historique — raf check`);
+    return 0;
+}
+function news([sub, ...args], plan, dir, today, values, io, refuseLongTitle, hypotheses) {
+    const lots = plan.lots();
+    switch (sub) {
+        case 'new': {
+            if (args.length === 0)
+                throw new RafError('usage : cadence news new <lot…> [--title t]');
+            for (const id of args)
+                plan.lot(id);
+            // Mesuré comme newEntry l'écrit : espaces fusionnés.
+            const title = (values.title ?? plan.lot(args[0]).public ?? plan.lot(args[0]).title).replace(/\s+/g, ' ').trim();
+            refuseLongTitle(title, values.title === undefined ? ' — donner un titre court : cadence news new <lot> --title "…"' : '');
+            io.out(newEntry(dir, args, 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':
+            for (const e of loadEntries(dir))
+                io.out(`${e.date}  ${e.title}  (${e.lots.join(', ')})`);
+            return 0;
+        case 'check':
+        case 'build': {
+            const entries = loadEntries(dir);
+            const issues = newsIssues(lots, entries, dir, sub === 'check' ? hypotheses() : undefined);
+            for (const i of issues)
+                io.out(`✗ ${i.message}`);
+            // Le build refuse seulement ce qu'il ne saurait pas publier : entrée illisible, capture absente.
+            const blocking = sub === 'check' ? issues : issues.filter((i) => i.kind === 'bad-entry' || i.kind === 'missing-capture');
+            if (sub === 'check')
+                io.out(issues.length === 0 ? '✓ Nouveautés cohérentes avec le plan' : `${issues.length} écart(s)`);
+            if (blocking.length > 0)
+                return 1;
+            if (sub === 'build') {
+                const stamp = io.now();
+                const data = newsData(plan.project, entries, `${toDay(stamp)} ${stamp.toTimeString().slice(0, 5)}`);
+                for (const f of buildNews(data, dir, resolve(io.cwd, values.output ?? join(dir, 'site'))))
+                    io.out(f);
+            }
+            return 0;
+        }
+        default:
+            throw new RafError('usage : cadence news new|list|check|stamp|build');
+    }
+}
+/** raf commits <lot> : les commits que compte la porte de revue. */
+export function cmdCommits(c) {
+    const { rest, io, root, loadPlan, need } = c;
+    need(1, 'commits <lot>');
+    const plan = loadPlan();
+    const id = rest[0];
+    knownLot(plan, id, 'les commits se listent par lot, pas par sous-tâche');
+    // 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));
+    for (const line of repoSections(plan, root, plan.lot(id)))
+        io.out(line);
+    return 0;
+}
+/** raf show <lot> [--notes]. */
+export function cmdShow(c) {
+    const { rest, values, io, root, loadPlan, need } = c;
+    need(1, 'show <lot> [--notes]');
+    const plan = loadPlan();
+    const lot = knownLot(plan, rest[0], 'show se lit par lot, pas par sous-tâche');
+    const notes = lot.notes.map((n) => `${n.date}  ${n.text}`);
+    if (values.notes) {
+        for (const n of notes)
+            io.out(n);
+        return 0;
+    }
+    for (const line of lotLines(plan, lot))
+        io.out(line);
+    if (notes.length) {
+        io.out('notes :');
+        // Les lignes suivantes d'une note multiligne s'alignent sous son texte, pas en colonne 0.
+        for (const n of lot.notes)
+            io.out(`  ${n.date}  ${n.text.replace(/\n/g, `\n${' '.repeat(n.date.length + 4)}`)}`);
+    }
+    const commits = lotWork(plan, root, lot.id).reverse();
+    io.out(`commits (${commits.length}) :`);
+    for (const c of commits)
+        io.out(`  ${short(c)}`);
+    for (const line of repoSections(plan, root, lot, '  '))
+        io.out(line);
+    return 0;
+}
+/** raf list [--status s] [--json]. */
+export function cmdList(c) {
+    const { values, io, loadPlan } = c;
+    const plan = loadPlan();
+    if (values.status && !STATUSES.includes(values.status))
+        throw new RafError(`statut inconnu : ${values.status}`);
+    const shown = plan.lots().filter((l) => !values.status || l.status === values.status);
+    if (values.json)
+        io.out(JSON.stringify(shown.map(lotJson), null, 2));
+    else
+        for (const l of shown)
+            io.out(`${l.id.padEnd(6)} ${l.status.padEnd(8)} ${l.quickwin ? '⚡ ' : ''}${l.title}`);
+    return 0;
+}
+/** raf check : les écarts entre le plan et l'historique, code 1 s'il y en a. */
+export function cmdCheck(c) {
+    const { values, io, today, root, loadPlan, newsDir } = c;
+    if (values.ignored) {
+        const list = loadPlan().acknowledged;
+        if (list.length === 0)
+            io.out('aucun commit acquitté');
+        for (const a of list)
+            io.out(`${a.sha ? a.sha.slice(0, 7) : 'sujet  '} ${a.subject ?? ''}  (${a.date}${a.reason ? ` — ${a.reason}` : ''})`);
+        return 0;
+    }
+    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(loadPlan(), root, newsDir, today, { since: values.since, idle });
+    for (const i of issues)
+        io.out(`${i.warning ? '⚠' : '✗'} ${i.message}`);
+    // Un avertissement s'affiche mais ne fait pas échouer : seuls les écarts comptent pour le code de sortie.
+    const errors = issues.filter((i) => !i.warning).length;
+    const warnings = issues.length - errors;
+    io.out(errors === 0 ? `✓ plan et historique cohérents${warnings ? ` (${warnings} avertissement(s))` : ''}` : `${errors} écart(s)${warnings ? `, ${warnings} avertissement(s)` : ''}`);
+    return errors === 0 ? 0 : 1;
+}
+/** raf gantt [-o fichier] : la page Gantt du plan. */
+export function cmdGantt(c) {
+    const { values, io, today, root, planPath, loadPlan } = c;
+    const plan = loadPlan();
+    const lots = plan.lots();
+    const linked = linkCommits(lots, planCommits(plan, root), plan.refs);
+    const stamp = io.now();
+    const html = renderGantt(ganttData(plan.project, schedule(lots, workByLot(plan, root, linked), today), today, `${toDay(stamp)} ${stamp.toTimeString().slice(0, 5)}`));
+    const out = resolve(io.cwd, values.output ?? join(dirname(planPath), 'gantt.html'));
+    mkdirSync(dirname(out), { recursive: true });
+    writeFileSync(out, html);
+    io.out(out);
+    return 0;
+}
+/** raf now : ce qui est en cours, la suite, les derniers terminés. */
+export function cmdNow(c) {
+    return now(c.loadPlan(), c.root, c.newsDir, c.today, c.io);
+}
+/** raf news … : les entrées Nouveautés. */
+export function cmdNews(c) {
+    const { rest, values, io, today, root, configPath, loadPlan, newsDir, refuseLongTitle } = c;
+    return news(rest, loadPlan(), newsDir, today, values, io, refuseLongTitle, () => hypothesesOf(root, configPath));
+}
+/** cadence ref coverage lit le plan (les lots faits qui citent les éléments) : il passe après le choix du plan, les autres ref n'y touchent pas (L367). */
+export function cmdRef(c) {
+    const { rest, io, root, configPath, loadPlan } = c;
+    return coverageCommand(rest.slice(1), loadPlan, io, { repo: root, specDir: readOrchestrateConfig(configPath).spec.dir });
+}