@sylad/cadence 1.41.0 → 1.42.1

package/.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
     {
       "name": "cadence",
       "description": "Session start and close rituals driven by a versioned plan (raf), and deliveries proven by their effect. Needs the cadence CLI (npm i -g @sylad/cadence).",
-      "version": "1.41.0",
+      "version": "1.42.1",
       "source": "./",
       "author": {
         "name": "Sylvain Ladoire"

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "cadence",
   "description": "A repo-native working method: session start and close rituals driven by a versioned plan (raf), deliveries proven by their effect, and three reviewer agents (UX, code, QA).",
-  "version": "1.41.0",
+  "version": "1.42.1",
   "author": { "name": "Sylvain Ladoire" },
   "homepage": "https://github.com/Sylad/cadence",
   "repository": "https://github.com/Sylad/cadence",

package/dist/archive.js

@@ -29,13 +29,17 @@ export function selectArchivable(lots, before, blocked = () => null) {
 }
 /** Le numéro d'un identifiant (`L12` → 12) ; NaN pour un identifiant sans numéro. */
 const num = (id) => Number(/\d+$/.exec(id)?.[0] ?? NaN);
+/** La clé d'un lot archivé qui garde sa place : l'identifiant du lot qui le précédait dans le plan présenté (vide : il le commençait). */
+export const PLACE_KEY = 'place';
 /**
- * Les lots archivés remis à leur place parmi ceux du fichier actif : chacun juste avant le premier lot actif de numéro plus grand, à la fin
- * sinon, les archivés entre eux par numéro. L'ordre du fichier actif ne bouge jamais ; un plan que `raf add` tient dans l'ordre des numéros
- * (le cas ordinaire) se lit exactement comme avant l'archivage (L396).
+ * Les lots archivés remis à leur place parmi ceux du fichier actif. Un lot qui porte un rang (`places` : id → id du lot qui le précédait
+ * dans le plan présenté au moment de l'archivage, `raf archive` le pose sur tout lot archivé dès que `plan.idPattern` est déclaré : le nombre final d'un id ne dit alors rien de
+ * l'ordre) revient juste après ce lot, en tête quand le rang est vide, à la fin quand le lot du rang n'existe plus. Les autres vont juste
+ * avant le premier lot actif de numéro plus grand, à la fin sinon, entre eux par numéro. L'ordre du fichier actif ne bouge jamais ; un plan que
+ * `raf add` tient dans l'ordre des numéros (le cas ordinaire) se lit exactement comme avant l'archivage (L396).
  */
-export function mergeArchived(archived, active) {
-    const queue = [...archived].sort((a, b) => num(a.id) - num(b.id) || 0);
+export function mergeArchived(archived, active, places = new Map()) {
+    const queue = archived.filter((l) => !places.has(l.id)).sort((a, b) => num(a.id) - num(b.id) || 0);
     const out = [];
     for (const lot of active) {
         const n = num(lot.id);
@@ -43,7 +47,100 @@ export function mergeArchived(archived, active) {
             out.push(queue.shift());
         out.push(lot);
     }
-    return [...out, ...queue];
+    out.push(...queue);
+    return placeRanked(out, archived.filter((l) => places.has(l.id)), places);
+}
+/**
+ * Pose les lots à rang derrière leur prédécesseur, en un passage (L536 : sous `plan.idPattern` les archivés forment une seule chaîne de rangs,
+ * un plan de 685 lots ne peut pas payer k²·n à chaque lecture). Les lots d'un même rang se suivent dans l'ordre d'archivage (celui du fichier),
+ * chacun suivi des lots dont il est lui-même le rang ; le rang vide ouvre le plan. Un lot dont le prédécesseur ne viendra jamais (inconnu,
+ * cycle, lui-même) va à la fin du plan, dans l'ordre d'archivage.
+ */
+function placeRanked(out, ranked, places) {
+    const followers = new Map();
+    for (const l of ranked) {
+        const from = places.get(l.id);
+        followers.set(from, [...(followers.get(from) ?? []), l]);
+    }
+    const result = [];
+    const placed = new Set();
+    // Un lot posé entraîne ses suiveurs, puis les leurs : le parcours en profondeur (pile explicite, une chaîne peut être longue) rend
+    // exactement l'ordre que donnait la pose tour par tour.
+    const emit = (from) => {
+        const stack = [[...(followers.get(from) ?? [])].reverse()];
+        while (stack.length > 0) {
+            const next = stack[stack.length - 1].pop();
+            if (next === undefined)
+                stack.pop();
+            else if (!placed.has(next)) {
+                result.push(next);
+                placed.add(next);
+                stack.push([...(followers.get(next.id) ?? [])].reverse());
+            }
+        }
+    };
+    emit('');
+    // Un prédécesseur dont l'id est aussi dans le fichier actif (plan déjà en erreur) : les suiveurs vont derrière celui du fichier.
+    const seen = new Set();
+    for (const lot of out) {
+        result.push(lot);
+        if (!seen.has(lot.id))
+            emit(lot.id);
+        seen.add(lot.id);
+    }
+    return [...result, ...ranked.filter((l) => !placed.has(l))];
+}
+/**
+ * Les rangs à réécrire quand des lots archivés rouvrent (`back`, parmi `nodes`, les lots de toutes les archives) : un lot dont le `place:` nommait un lot
+ * rouvert est re-pointé sur le prédécesseur de celui-ci, de proche en proche, pour que seul le lot rouvert bouge dans le plan présenté (L536). Un lot rouvert
+ * sans rang (archivé avant `plan.idPattern`) prend pour prédécesseur celui du plan présenté (`order`, lu seulement alors). Rend les lots restés archivés dont le rang change.
+ */
+function repointPlaces(nodes, back, order) {
+    const places = new Map();
+    for (const n of nodes) {
+        const v = n.get(PLACE_KEY);
+        if (typeof v === 'string' || v === null)
+            places.set(n, v ?? '');
+    }
+    let presented;
+    for (const n of back.filter((b) => !places.has(b))) {
+        presented ??= order();
+        places.set(n, presented[presented.indexOf(String(n.get('id'))) - 1] ?? '');
+    }
+    const moved = new Map();
+    for (const n of back) {
+        const id = String(n.get('id'));
+        for (const s of nodes.filter((o) => places.get(o) === id)) {
+            places.set(s, places.get(n));
+            if (!back.includes(s))
+                moved.set(s, places.get(s));
+        }
+    }
+    return moved;
+}
+/**
+ * Les lots archivés qui ne sont plus clos (`raf todo` sur un lot done archivé) reviennent à la fin de la liste `active` du plan : seuls eux bougent,
+ * les lots restés archivés dont le `place:` les nommait sont re-pointés (`repointPlaces`, L536). Chaque archive touchée est marquée `dirty`.
+ */
+export function reopenArchived(archives, active, order) {
+    const nodes = archives.flatMap((a) => archiveLots(a.doc).items.filter(isMap).map((n) => ({ a, n: n })));
+    const back = nodes.filter(({ n }) => !['done', 'dropped'].includes(String(n.get('status'))));
+    if (back.length === 0)
+        return;
+    const moved = repointPlaces(nodes.map(({ n }) => n), back.map(({ n }) => n), order);
+    for (const { a, n } of nodes) {
+        if (back.some((b) => b.n === n)) {
+            const seq = archiveLots(a.doc);
+            seq.items = seq.items.filter((i) => i !== n);
+            n.delete(PLACE_KEY);
+            active.add(n);
+        }
+        else if (moved.has(n))
+            n.set(PLACE_KEY, moved.get(n));
+        else
+            continue;
+        a.dirty = true;
+    }
 }
 /** Année de rangement d'un lot : celle de sa fin, à défaut de sa création, à défaut d'aujourd'hui. */
 export function archiveYear(lot, today) {

package/dist/audit.js

@@ -6,7 +6,7 @@ import { changedFiles, fileAt, isAncestor, preloadChangedFiles, readCommits } fr
 import { citedRefs, linkCommits, scopeOf } from './link.js';
 import { PLAN_DEFAULT, PLAN_LEGACY, readDocsConfig, readNewsConfig, readOrchestrateConfig } from './config.js';
 import { ficheHypotheses } from './spec.js';
-import { docSyncGaps, filesOf, gapMessage } from './docsync.js';
+import { gapMessage, lotDocSyncGaps } from './docsync.js';
 import { loadEntries, newsIssues, PUBLIC_TITLE_DEFAULT, publicTitleTooLong, reusedNewsTitle } from './news.js';
 import { isRecurring } from './recurring.js';
 import { resourceIssues } from './resources.js';
@@ -233,7 +233,7 @@ function docSyncIssues(plan, root, byLot) {
         .lots()
         .filter((l) => !l.docsOk)
         .filter((l) => l.status === 'doing' || (l.status === 'done' && !!since && !!l.finished && l.finished >= since))
-        .flatMap((l) => docSyncGaps(sync, filesOf(root, workCommits(plan, root, byLot.get(l.id) ?? []))).map((g) => ({ message: gapMessage(l.id, g) })));
+        .flatMap((l) => lotDocSyncGaps(sync, root, workCommits(plan, root, byLot.get(l.id) ?? [])).map((g) => ({ message: gapMessage(l.id, g) })));
 }
 /** Commits qui portent du travail sur un lot : ni antérieurs à l'adoption du plan, ni acquittés (`raf ignore`), ni réduits au plan, ni une simple version. */
 function workCommits(plan, root, commits) {

package/dist/clean.js

@@ -219,7 +219,3 @@ export function scanStale(root, patterns, days, today) {
         unreadable: [...unreadable].sort(),
     };
 }
-/** Éléments périmés à proposer (voir `scanStale`), du plus vieux au plus récent. Ne supprime rien. */
-export function staleFiles(root, patterns, days, today) {
-    return scanStale(root, patterns, days, today).stale;
-}

package/dist/cli/context.js

@@ -0,0 +1,129 @@
+// Le contexte commun des commandes de raf et de cadence (L488, sorti de cli.ts) : les options, ce que dispatch construit, les assistants partagés.
+import { parseArgs } from 'node:util';
+import { dirname, join, relative, resolve } from 'node:path';
+import { defaultPlan, PLAN_DEFAULT, PLAN_LEGACY, readNewsConfig, readPlanConfig } from '../config.js';
+import { shellQuote } from '../deliver.js';
+import { gitRoot, isTracked } from '../git.js';
+import { publicTitleTooLong } from '../news.js';
+import { Plan, RafError } from '../plan.js';
+/** Les options de la ligne de commande, toutes commandes confondues : une option n'a de sens que pour certaines, chaque commande lit les siennes. */
+const OPTIONS = {
+    file: { type: 'string' },
+    project: { type: 'string' },
+    prefix: { type: 'string' },
+    'no-hook': { type: 'boolean' },
+    estimate: { type: 'string' },
+    quickwin: { type: 'boolean' },
+    visible: { type: 'boolean' },
+    screen: { type: 'string' },
+    spec: { type: 'boolean' },
+    local: { type: 'boolean' },
+    public: { type: 'string' },
+    every: { type: 'string' },
+    dir: { type: 'string' },
+    title: { type: 'string' },
+    after: { type: 'string' },
+    uses: { type: 'string' },
+    set: { type: 'string', multiple: true },
+    parent: { type: 'string' },
+    id: { type: 'string' },
+    under: { type: 'string' },
+    force: { type: 'boolean' },
+    back: { type: 'boolean' },
+    reason: { type: 'string' },
+    porteur: { type: 'string' },
+    status: { type: 'string' },
+    since: { type: 'string' },
+    before: { type: 'string' },
+    idle: { type: 'string' },
+    ttl: { type: 'string' },
+    session: { type: 'string' },
+    all: { type: 'boolean' },
+    depth: { type: 'string' },
+    output: { type: 'string', short: 'o' },
+    config: { type: 'string' },
+    'dry-run': { type: 'boolean' },
+    sha: { type: 'string' },
+    retry: { type: 'string' },
+    gate: { type: 'boolean' },
+    clear: { type: 'boolean' },
+    ignored: { type: 'boolean' },
+    notes: { type: 'boolean' },
+    json: { type: 'boolean' },
+    verbose: { type: 'boolean' },
+    classify: { type: 'boolean' },
+    model: { type: 'string' },
+    cache: { type: 'string' },
+    'cache-sous-causes': { type: 'string' },
+    sample: { type: 'string' },
+    sections: { type: 'string' },
+    slug: { type: 'string' },
+    quoi: { type: 'string' },
+    'sans-rendu': { type: 'boolean' },
+    out: { type: 'string' },
+    seuil: { type: 'string' },
+    'model-b': { type: 'string' },
+    double: { type: 'boolean' },
+    largeur: { type: 'string' },
+    until: { type: 'string' },
+    help: { type: 'boolean', short: 'h' },
+};
+export function parseCli(argv) {
+    return parseArgs({ args: argv, allowPositionals: true, options: OPTIONS });
+}
+/** Le contexte d'une commande qui lit le plan : ce que dispatch construit une fois, après les commandes qui n'en ont pas besoin. */
+export function buildCtx(base) {
+    const { command, rest, values, io, root } = base;
+    // 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, root);
+    // Le défaut (ni --file, ni RAF_FILE, ni plan:) : .cadence/raf.yaml, ou le docs/plan/raf.yaml hérité, dont le déplacement est proposé sur stderr (L246).
+    // --file et RAF_FILE se lisent depuis le dossier courant ; le plan: de cadence.yaml, depuis la racine du dépôt où est ce fichier.
+    const chosen = values.file ?? io.env.RAF_FILE ?? planConfig?.path;
+    const fallback = chosen === undefined ? defaultPlan(root) : null;
+    const planPath = resolve(io.cwd, values.file ?? io.env.RAF_FILE ?? (planConfig?.path !== undefined ? resolve(root, planConfig.path) : fallback.path));
+    if (fallback?.legacy && !installing)
+        (io.notice ?? io.err)(legacyPlanLine(root, fallback.legacy));
+    const loadPlan = () => Plan.load(planPath, { ...planConfig?.settings, config: configPath });
+    const newsDir = resolve(io.cwd, values.dir ?? join(root, 'docs/nouveautes'));
+    // Limite DÉCLARÉE (news.publicTitleMax) : sans clé, seul « raf check » avertit ; avec, la pose d'un titre public est refusée.
+    const refuseLongTitle = (text, hint = '') => {
+        const max = readNewsConfig(configPath).publicTitleMax;
+        const m = max === undefined ? null : publicTitleTooLong(text, max);
+        if (m)
+            throw new RafError(m + hint);
+    };
+    const need = (n, usage) => {
+        if (rest.length < n)
+            throw new RafError(`usage : raf ${usage}`);
+    };
+    return { ...base, configPath, planConfig, planPath, chosen, loadPlan, newsDir, refuseLongTitle, need };
+}
+/** `--verbose` (L453) : la ligne `id  état  titre entier` du lot touché par `done`, `ux`, `review`, `note`, `move`, `public` ; sans lui, rien de plus (une sous-tâche n'a pas de ligne). */
+export function touchedLot(plan, id, verbose, io) {
+    const lot = verbose ? plan.lots().find((l) => l.id === id) : undefined;
+    if (lot)
+        io.out(`${lot.id}  ${lot.status}  ${lot.title}`);
+}
+export function knownLot(plan, id, subtask) {
+    const lot = plan.lots().find((l) => l.id === id);
+    if (!lot)
+        throw new RafError(id.includes('/') ? `${subtask} : ${id}` : `lot inconnu : ${id}`);
+    return lot;
+}
+/** Le plan, relatif à la racine du dépôt git (comme les fichiers d'un commit), séparateurs `/`. */
+export function planFileIn(root, planPath) {
+    return relative(gitRoot(root) ?? root, planPath).split('\\').join('/');
+}
+/**
+ * La ligne stderr d'un docs/plan/raf.yaml hérité : le déplacement proposé (jamais fait), ou l'avertissement quand .cadence/raf.yaml existe aussi.
+ * La commande proposée commence par `cd <racine>` : elle s'exécute telle quelle depuis n'importe quel dossier (et non depuis la racine
+ * seulement) et, sous `session --all`, elle nomme le projet dont il s'agit.
+ */
+function legacyPlanLine(root, legacy) {
+    if (legacy === 'ignored')
+        return `raf: ${PLAN_LEGACY} est ignoré : ${PLAN_DEFAULT} existe aussi et fait foi (supprimer ou fusionner l'ancien)`;
+    return `raf: ${PLAN_LEGACY} est l'ancien emplacement du plan ; le déplacer : cd ${shellQuote(root)} && mkdir -p ${dirname(PLAN_DEFAULT)} && ${gitRoot(root) && isTracked(root, PLAN_LEGACY) ? 'git mv' : 'mv'} ${PLAN_LEGACY} ${PLAN_DEFAULT}`;
+}

package/dist/cli/deliver-commands.js

@@ -0,0 +1,114 @@
+// deliver, verify (et sa porte --gate) et local : la livraison du projet (L488, sorti de cli.ts).
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { defaultPlan, readDocsConfig, readOrchestrateConfig, readPlanConfig, readVerifyConfig } from '../config.js';
+import { deliver, parseDeliverConfig, realDeps } from '../deliver.js';
+import { defaultTarget, realCheckDeps, verifyCommand } from '../verify.js';
+import { verifyGate } from '../verify-gate.js';
+import { gitRoot, resolveCommit } from '../git.js';
+import { loadEntries } from '../news.js';
+import { RafError } from '../plan.js';
+import { waveHolding } from '../repo-busy.js';
+import { cadenceHome, waveLotsIn } from '../orchestrate/registry.js';
+import { blockingLots, LABEL } from '../orchestrate/table.js';
+import { localCommand, localLotOf } from '../local-task.js';
+import { sharedStateDir } from '../state.js';
+import { planFileIn } from './context.js';
+/**
+ * Ce qu'une livraison verte annonce et ouvre (lots livrés, article à rafraîchir, L144) : pour `cadence deliver` et pour la ligne verte
+ * que `cadence verify` inscrit (L435). Sans `public:`, un lot visible tire son titre de sa Nouveauté la plus récente.
+ */
+function deliveredEffects(p) {
+    const { root, configPath, newsDir, io } = p;
+    const publicTitle = (lot) => lot.public ?? (lot.visible ? loadEntries(newsDir).find((e) => e.lots.includes(lot.id))?.title : undefined);
+    const plan = existsSync(p.planPath) ? p.loadPlan() : null;
+    return { root, plan, today: p.today, articles: readDocsConfig(configPath).articles, publicTitle, planCommit: readPlanConfig(configPath, root)?.commit, waveId: p.waveId, out: io.out, err: io.err };
+}
+/** `verify --gate --sha rév [--project dossier]` (L348) : la porte du projet rejouée au sha ; `--project` est un sous-dossier du dossier courant qui a son propre dépôt. */
+async function verifyGateCommand(values, io) {
+    if (values.sha === undefined)
+        throw new RafError('verify --gate : --sha obligatoire (le sha à re-vérifier, jamais la tête mouvante d\'une vague)');
+    if (values.retry !== undefined)
+        throw new RafError('verify --gate : --retry ne va qu\'à verify seul (deliver.verify)');
+    const dir = values.project === undefined ? io.cwd : resolve(io.cwd, values.project);
+    if (values.project !== undefined && !existsSync(dir))
+        throw new RafError(`verify --gate : --project ${values.project} : dossier introuvable sous ${io.cwd}`);
+    const top = gitRoot(dir);
+    if (!top)
+        throw new RafError('verify --gate : à lancer dans un dépôt git (ou --project vers le dossier d\'un projet)');
+    if (values.project !== undefined && realpathSync(top) !== realpathSync(dir))
+        throw new RafError(`verify --gate : ${values.project} n'a pas son propre dépôt git (dépôt parent : ${top})`);
+    const configPath = resolve(io.cwd, values.config ?? join(top, 'cadence.yaml'));
+    const sha = resolveCommit(top, values.sha);
+    if (!sha)
+        throw new RafError(`verify --gate : --sha ${values.sha} : commit introuvable dans ${top}`);
+    // Le plan du projet (L444) : les commits qui ne changent que lui au-dessus du sha reprennent la porte du sha dessous. Illisible, il n'est pas cherché : la porte se rejoue.
+    let planFile;
+    try {
+        const configured = readPlanConfig(configPath, top)?.path;
+        planFile = planFileIn(top, configured !== undefined ? resolve(top, configured) : defaultPlan(top).path);
+    }
+    catch {
+        planFile = undefined;
+    }
+    return verifyGate({ repo: top, sha, config: readOrchestrateConfig(configPath), verify: readVerifyConfig(configPath), launchDirs: [io.cwd, top, dirname(top)], planFile, now: io.now, out: io.out });
+}
+/** cadence deliver : refusé pendant une vague sauf un sha livrable, puis la livraison du projet. */
+export function cmdDeliver(c) {
+    const { rest, values, io, today, root, configPath, planPath, loadPlan, newsDir } = c;
+    if (!gitRoot(io.cwd))
+        throw new RafError('deliver : à lancer dans un dépôt git');
+    const orchestrating = waveHolding(root, 'deliver');
+    if (orchestrating) {
+        const refusal = `deliver : orchestration en cours (vague ${orchestrating.wave}, pid ${orchestrating.pid})`;
+        if (values.sha === undefined)
+            throw new RafError(`${refusal} — livrer une fois les lots de ce dépôt finis (le verrou tombe dès que tous sont prêts ou rendus), ou un sha « livrable jusqu'à » de la vague (--sha)`);
+        // L277 : un sha dont tous les commits de la vague citent des lots prêts se livre au fil de l'eau ; l'état de la vague illisible ou un sha inconnu : refus.
+        const lots = waveLotsIn(cadenceHome(), orchestrating.pid, root);
+        const target = resolveCommit(root, values.sha);
+        if (lots === null)
+            throw new RafError(`${refusal} — état de la vague illisible : --sha ${values.sha} ne peut pas être vérifié`);
+        if (!target)
+            throw new RafError(`${refusal} — --sha ${values.sha} : commit introuvable`);
+        const { blocking, unreadable } = blockingLots(lots, root, target);
+        if (blocking.length > 0) {
+            throw new RafError(`${refusal} — ${target.slice(0, 7)} contient des commits de lots pas prêts : ${blocking.map((l) => `${l.project}:${l.lot} (${LABEL[l.status]})`).join(', ')} ; livrer un sha antérieur (« livrable jusqu'à » du tableau de la vague) ou attendre leur fin`);
+        }
+        if (unreadable.length > 0) {
+            throw new RafError(`${refusal} — commits illisibles (plan du projet ou dépôt) des lots pas prêts ${unreadable.map((l) => `${l.project}:${l.lot} (${LABEL[l.status]})`).join(', ')} : --sha ${values.sha} ne peut pas être vérifié ; rétablir le plan ou attendre la fin de ces lots`);
+        }
+    }
+    if (!existsSync(configPath))
+        throw new RafError(`pas de configuration de livraison : ${configPath} (voir « cadence.yaml » dans docs/deliver.md du paquet @sylad/cadence)`);
+    const config = parseDeliverConfig(readFileSync(configPath, 'utf8'), configPath);
+    const effects = deliveredEffects({ root, configPath, planPath, loadPlan, newsDir, today, waveId: orchestrating?.wave, io });
+    return deliver({ ...effects, state: sharedStateDir(root), config, dryRun: !!values['dry-run'], sha: values.sha, duringWave: !!orchestrating, args: rest }, realDeps(root));
+}
+/** cadence verify [--gate] : rejoue deliver.verify, ou la porte du projet. */
+export function cmdVerify(c) {
+    const { values, io, today, root, configPath, planPath, loadPlan, newsDir } = c;
+    if (values.gate)
+        return verifyGateCommand(values, io);
+    if (!gitRoot(io.cwd))
+        throw new RafError('verify : à lancer dans un dépôt git');
+    if (!existsSync(configPath))
+        throw new RafError(`pas de configuration : ${configPath} (voir « cadence.yaml » dans docs/deliver.md du paquet @sylad/cadence)`);
+    const retry = values.retry === undefined ? 0 : Number(values.retry);
+    if (!Number.isFinite(retry) || retry < 0)
+        throw new RafError(`--retry invalide : ${values.retry} (secondes, 0 ou plus)`);
+    const config = parseDeliverConfig(readFileSync(configPath, 'utf8'), configPath);
+    const target = values.sha ? { sha: resolveCommit(root, values.sha) ?? '', note: null } : defaultTarget(root, config);
+    if (values.sha && !target.sha)
+        throw new RafError(`--sha ${values.sha} : commit introuvable`);
+    // Une ligne verte écrite par verify (L435) est une livraison : mêmes effets que deliver (lots annoncés, article à rafraîchir, L144).
+    // verify lit le verrou sans refuser : une tâche locale du lead (L519) n'empêche pas de rejouer les vérifications, et n'est pas une vague à citer.
+    const holding = waveHolding(root);
+    const waveId = holding && !localLotOf(holding.wave) ? holding.wave : undefined;
+    const effects = () => deliveredEffects({ root, configPath, planPath, loadPlan, newsDir, today, waveId, io });
+    return verifyCommand({ config, sha: target.sha, note: target.note, retry, out: io.out, journal: { dir: sharedStateDir(root), day: today, effects } }, realCheckDeps(root));
+}
+/** cadence local start|done|abort : la tâche locale du lead. */
+export function cmdLocal(c) {
+    const { rest, values, io, today, root, loadPlan } = c;
+    return localCommand(rest, values.ttl, { repo: gitRoot(root) ?? root, loadPlan, today, now: io.now, gate: (sha) => verifyGateCommand({ sha }, io), out: io.out, err: io.err });
+}

package/dist/cli/gates.js

@@ -0,0 +1,234 @@
+// Les portes : raf ux / raf review, et les trois hooks git (pre-commit, post-commit, pre-push) (L488, sorti de cli.ts).
+import { existsSync, readFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { readHookConfig, readOrchestrateConfig } from '../config.js';
+import { repoShas, resolveLotRepos } from '../repos.js';
+import { exemptPlanOnly, isPlanOnly, lotWork, ownFiles } from '../audit.js';
+import { PLAN_ACTIONS } from '../plan-commit.js';
+import { printUncommittedPlan } from '../plan-uncommitted.js';
+import { matchesHead, readCommits, stage, stagedFiles, syncIndexWithHead } from '../git.js';
+import { installHook, pendingCommitMessage, REFUSED } from '../hook.js';
+import { gateRefusal, pushRefusal, UNGATED_ENV } from '../push-guard.js';
+import { citedRefs } from '../link.js';
+import { loadEntries } from '../news.js';
+import { RafError } from '../plan.js';
+import { dueLine, isRecurring } from '../recurring.js';
+import { TITLE_MAX, truncate } from '../lead.js';
+import { waveHolding } from '../repo-busy.js';
+import { cadenceHome, waveLotsIn } from '../orchestrate/registry.js';
+import { localLotOf } from '../local-task.js';
+import { planFileIn, touchedLot } from './context.js';
+const GATES = {
+    ux: { on: 'revue UX obligatoire pour les lots visibles', already: 'revue UX déjà active', action: PLAN_ACTIONS.uxRecorded },
+    review: { on: 'revue de code obligatoire pour les lots à commits', already: 'revue de code déjà active', action: PLAN_ACTIONS.reviewRecorded },
+};
+/** « 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, opts) {
+    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 {
+        // Les dépôts voisins du lot : un dépôt qu'on ne peut pas lire ferait enregistrer un verdict sur un sha non lu.
+        const neighbours = plan.readonly || rest[0].includes('/') ? undefined : resolveLotRepos(root, plan.lots().find((l) => l.id === rest[0]) ?? {});
+        if (neighbours?.problems.length)
+            throw new RafError(`${neighbours.problems.join(' ; ')} — la revue de code relit aussi les dépôts du lot`);
+        plan.recordReview(rest[0], verdict, today, plan.readonly ? null : (lotWork(plan, root, rest[0])[0]?.sha ?? null), neighbours?.repos.length ? repoShas(plan, neighbours.repos, rest[0]) : undefined);
+    }
+    plan.save();
+    touchedLot(plan, rest[0], opts.verbose, io);
+    // Comme `raf done` (L371) : le plan et la copie publiée que `plan.onWrite` vient de régénérer partent dans le même commit (L509).
+    printUncommittedPlan(io.out, plan, root, rest[0], opts.commit, GATES[kind].action);
+    return 0;
+}
+/** Un titre de lot n'est jamais rendu en entier par défaut (L453) : ~300 caractères répétés à chaque commande, chaque commit de plan. */
+function shortTitle(title, verbose) {
+    return verbose ? title : truncate(title, TITLE_MAX);
+}
+/**
+ * Pre-commit : un commit qui cite un lot encore todo. `warn` (défaut) : rien ici, le post-commit avertit ; `refuse` :
+ * échoue (REFUSED) avec « raf start <id> » ; `start` : démarre le lot et met le plan dans l'index, donc dans CE commit,
+ * mais seulement si le plan est identique à HEAD : sinon rien n'est démarré (message, puis avertissement du post-commit).
+ * Ne rend REFUSED que pour un refus : toute autre panne laisse le commit passer. Sans message lisible (éditeur), rien.
+ */
+function preCommit(load, mode, root, today, io) {
+    if (!load || !mode || mode === 'warn')
+        return 0;
+    try {
+        const message = pendingCommitMessage(io.env);
+        if (message === null)
+            return 0;
+        const plan = load();
+        const [subject = '', ...body] = message.split('\n');
+        const refs = citedRefs({ sha: '', day: today, subject, body: body.join('\n').trim() }, plan.refs);
+        const staged = stagedFiles(root);
+        const own = ownFiles(plan, root);
+        // Entretien du plan : tous les fichiers du commit sont ceux du plan (la configuration seule ne compte pas).
+        if (staged.length > 0 && staged.every((f) => own.has(f) && f !== relative(root, plan.configFile ?? join(root, 'cadence.yaml'))))
+            return 0;
+        const todo = [...new Set(refs.map((r) => r.lot))].filter((id) => {
+            const lot = plan.lots().find((l) => l.id === id);
+            return lot?.status === 'todo' && !isRecurring(lot);
+        });
+        if (todo.length === 0)
+            return 0;
+        if (mode === 'refuse') {
+            for (const id of todo)
+                io.err(`raf: ${id} est encore todo — commit refusé (hook.autostart: refuse)${plan.readonly ? '' : ` : raf start ${id}`} (--no-verify pour passer outre)`);
+            return REFUSED;
+        }
+        if (plan.readonly)
+            return 0;
+        const file = relative(root, plan.path);
+        // Un plan déjà modifié (stagé ou non) : le restager emporterait ces modifications dans ce commit, ou, sur un
+        // commit partiel, les perdrait. On ne démarre rien ; le post-commit avertit comme en mode warn.
+        if (!matchesHead(root, file)) {
+            io.err(`raf: plan modifié non commité : démarrage automatique sauté (hook.autostart: start), raf start ${todo.join(' ')} à la main`);
+            return 0;
+        }
+        for (const id of todo)
+            plan.setStatus(id, 'doing', today, {});
+        try {
+            plan.save();
+        }
+        catch (e) {
+            if (!(e instanceof RafError))
+                throw e;
+            // plan.onWrite en échec (L346) : le plan est resté tel quel, le commit part sans lui et le dit.
+            io.err(`raf: démarrage automatique refusé : ${e.message} ; raf start ${todo.join(' ')} à la main`);
+            return 0;
+        }
+        for (const id of todo)
+            io.err(`raf: ${id} était todo — raf start ${id} fait par le hook, plan inclus dans ce commit`);
+        stage(root, file);
+        for (const f of plan.produced)
+            stage(root, f);
+    }
+    catch {
+        // Un hook ne doit jamais gêner un commit, hors refus.
+    }
+    return 0;
+}
+function postCommit(load, newsDir, root, today, io, mode, verbose) {
+    if (!load)
+        return 0;
+    try {
+        const plan = load();
+        if (mode === 'start' && !plan.readonly)
+            syncIndexWithHead(root, relative(root, plan.path));
+        const head = readCommits(root, { range: '-1' })[0];
+        if (!head)
+            return 0;
+        const refs = citedRefs(head, plan.refs);
+        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)) {
+                io.err('raf: commit sans lot — citer un identifiant la prochaine fois (raf now)');
+            }
+            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 (isRecurring(lot))
+                io.err(`raf: ${r.lot} est récurrent (${dueLine(lot, today)})${plan.readonly ? '' : ` — raf did ${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}) ${shortTitle(lot.title, verbose)}`);
+        }
+        const entries = loadEntries(newsDir);
+        for (const id of new Set(refs.map((r) => r.lot))) {
+            if (lots.get(id)?.visible && !entries.some((e) => e.lots.includes(id)))
+                io.err(`raf: ${id} est visible : cadence news new ${id}`);
+        }
+    }
+    catch {
+        // Un hook ne doit jamais gêner un commit.
+    }
+    return 0;
+}
+/**
+ * `raf hook pre-push` (L405), appelé par le hook que la vague pose : refuse (code 3) un push qui emporte un commit d'un lot pas prêt de la vague vivante
+ * du dépôt, ou dont un lot pas prêt a des commits illisibles (la garde de `deliver --sha`). Puis (L426), quand le projet déclare une porte, refuse un push dont
+ * le sha de tête n'a pas de verdict vert de `cadence verify --gate` (`CADENCE_PUSH_UNGATED=1` passe outre, et le dit) ; un commit qui ne change que le plan reprend le verdict de son parent (L432). Sans vague qui tient le dépôt, ou avec un état de vague illisible
+ * (avertissement), la première garde ne gêne jamais un push ; une config illisible laisse passer la seconde.
+ */
+function prePush(root, io, remoteName, configPath, planFile) {
+    let input = '';
+    try {
+        input = io.stdin ? io.stdin() : readFileSync(0, 'utf8');
+    }
+    catch {
+        return 0;
+    }
+    const holding = waveHolding(root);
+    // Une tâche locale du lead (L519) tient le dépôt comme une vague, mais n'a pas de lots de vague : rien à vérifier pour la première garde, et pas de faux « état illisible ».
+    if (holding && !localLotOf(holding.wave)) {
+        const lots = waveLotsIn(cadenceHome(), holding.pid, root);
+        if (lots === null) {
+            io.err(`raf: vague ${holding.wave} : état illisible, push non vérifié`);
+        }
+        else {
+            const refusal = pushRefusal(root, holding.wave, lots, input, remoteName || undefined);
+            if (refusal) {
+                io.err(`raf: ${refusal}`);
+                return REFUSED;
+            }
+        }
+    }
+    // La porte du projet (L426) : une config illisible ne gêne pas un push, comme un état de vague illisible.
+    let gate = false;
+    try {
+        const config = readOrchestrateConfig(configPath);
+        gate = Boolean(config.test || config.build);
+    }
+    catch {
+        return 0;
+    }
+    const refusal = gateRefusal(root, gate, input, planFile);
+    if (!refusal)
+        return 0;
+    if (io.env[UNGATED_ENV] === '1') {
+        io.err(`raf: ${refusal.replace(/^push refusé/, 'push passé outre')} — ${UNGATED_ENV}=1 est posée`);
+        return 0;
+    }
+    io.err(`raf: ${refusal}`);
+    return REFUSED;
+}
+/** raf hook install|pre-commit|post-commit|pre-push. */
+export function cmdHook(c) {
+    const { rest, values, io, today, root, configPath, planPath, loadPlan, newsDir } = c;
+    if (rest[0] === 'install') {
+        const { path, changed } = installHook(io.cwd);
+        io.out(changed ? `hook installé : ${path}` : `hook déjà présent : ${path}`);
+        return 0;
+    }
+    if (rest[0] === 'post-commit')
+        return postCommit(existsSync(planPath) ? loadPlan : null, newsDir, root, today, io, readHookConfig(configPath).autostart, !!values.verbose);
+    if (rest[0] === 'pre-commit')
+        return preCommit(existsSync(planPath) ? loadPlan : null, readHookConfig(configPath).autostart, root, today, io);
+    if (rest[0] === 'pre-push')
+        return prePush(root, io, rest[1], configPath, planFileIn(root, planPath));
+    throw new RafError('usage : raf hook install|pre-commit|post-commit|pre-push');
+}
+/** raf ux|review : active la porte, ou note le verdict d'un lot. */
+export function cmdGate(c) {
+    const { command, rest, values, io, today, root, planConfig, loadPlan } = c;
+    return gate(command, rest, loadPlan, root, today, io, { verbose: !!values.verbose, commit: planConfig?.commit });
+}