@sylad/cadence 1.40.0 → 1.41.0

package/dist/orchestrate/cycle.js

@@ -36,7 +36,7 @@ import { lotIds, referenceIdsText } from '../ref/coverage.js';
 import { avalFicheText, ficheContracts, ficheRules, hasScreenPart } from './aval.js';
 import { ficheReviewText, reviewedSheetText } from './fiche.js';
 import { bulletLines, maquetteText, reviewedText } from './maquette.js';
-import { answeredText, checkSpec, costlyHypotheses, ficheHasBack, ficheReady, findFiche, hypothesisLines, answerAltersRule, hypothesisNote, LEAD_SOURCE, ruleIdsSourcedByLead, sourceRules, specText } from './spec.js';
+import { answeredText, checkSpec, costlyHypotheses, ficheHasBack, ficheReady, findFiche, hypothesisLines, answerAltersRule, hypothesisNote, lightLot, LEAD_SOURCE, ruleIdsSourcedByLead, sourceRules, specText } from './spec.js';
 import { handBackWithoutFinding } from './no-finding.js';
 import { decisionsText, humanDecisions } from './decisions.js';
 import { LOCAL_PRECHECK_UNREADABLE, PRECHECK_UNREADABLE, expressSummary, lotKey, lotRepoPaths, neighbourDirs } from './state.js';
@@ -439,24 +439,19 @@ export function briefName(l, kind, integration = false) {
         return 'review-recheck'; // la revue d'intégration (R17) garde le gabarit qui porte {{integration}}
     return kind;
 }
-/** Gabarit de fiche livré avec le paquet, joint au brief de la spec (la session ne lit pas le dossier du paquet). */
-function ficheTemplate() {
+/** Fichier livré avec le paquet à côté des gabarits, joint à un brief (la session ne lit pas le dossier du paquet) ; undefined s'il manque. */
+function packageFile(name) {
     try {
-        return readFileSync(join(TEMPLATES_DIR, '..', 'fiche.yaml'), 'utf8');
+        return readFileSync(join(TEMPLATES_DIR, '..', name), 'utf8');
     }
     catch {
         return undefined;
     }
 }
+/** Gabarit de fiche livré avec le paquet, joint au brief de la spec. */
+const ficheTemplate = () => packageFile('fiche.yaml');
 /** Gabarit de la partie back de la fiche (L187), joint au brief de la spec d'un lot `spec: true`. */
-function ficheBackTemplate() {
-    try {
-        return readFileSync(join(TEMPLATES_DIR, '..', 'fiche-back.yaml'), 'utf8');
-    }
-    catch {
-        return undefined;
-    }
-}
+const ficheBackTemplate = () => packageFile('fiche-back.yaml');
 /** Le lot passe par l'étape spec : il déclare `screen:` (écran) ou `spec: true` (comportement sans écran, L188). */
 const hasSpecStage = (l) => !!(l.screen || l.specLot);
 /**
@@ -465,14 +460,7 @@ const hasSpecStage = (l) => !!(l.screen || l.specLot);
  */
 const partsOf = (c, fiche) => ({ screen: !!c.lot.screen, back: !!c.lot.specLot || (!!c.lot.screen && !!fiche && ficheHasBack(wd(c), fiche)) });
 /** Gabarit du lanceur de tests livré avec le paquet, joint au brief de l'étape accept. */
-function acceptRunner() {
-    try {
-        return readFileSync(join(TEMPLATES_DIR, '..', 'acceptation-runner.mjs'), 'utf8');
-    }
-    catch {
-        return undefined;
-    }
-}
+const acceptRunner = () => packageFile('acceptation-runner.mjs');
 /** Fiche du lot : celle de l'étape spec, ou la fiche retrouvée dans le dépôt (reprise). */
 function ficheOf(c) {
     const l = c.lot;
@@ -543,7 +531,7 @@ function briefFor(c, kind, local = false) {
         vars.spec = specText({
             dir: c.config.spec.dir,
             render: c.config.spec.render,
-            screen: l.screen,
+            screen: l.screen, light: lightLot(l, lot, c.config.maquette, wd(c), c.config.spec.dir),
             back,
             problems: l.specProblems,
             review: !reviewed.length ? undefined : back ? reviewedSheetText(reviewed, !!l.screen, session) : reviewedText(reviewed, session),
@@ -562,7 +550,7 @@ function briefFor(c, kind, local = false) {
         vars.reponse = '';
     }
     if (kind === 'maquette') {
-        vars.maquette = maquetteText({ fiche: ficheOf(c) ?? '', passes: l.maquette?.passes ?? 0, max: c.config.maquetteReviews, previous: l.maquetteConstats });
+        vars.maquette = maquetteText({ fiche: ficheOf(c) ?? '', passes: l.maquette?.passes ?? 0, max: c.config.maquetteReviews, previous: l.maquetteConstats, light: lightLot(l, lot, c.config.maquette, wd(c), c.config.spec.dir) });
         vars.reponse = '';
     }
     if (kind === 'accept') {
@@ -1455,6 +1443,9 @@ function afterMaquette(c, fiche) {
     // Des constats de la revue de fiche attendent la revue de la maquette (lot mixte) : les deux partent ensemble à la seconde passe `spec`.
     if (l.ficheConstats?.length)
         return 'spec';
+    // Une maquette légère n'a pas de règles de comportement à verrouiller : pas d'accept, même si orchestrate.accept est déclaré.
+    if (lightLot(l, c.loadPlan().lot(l.lot), c.config.maquette, wd(c), c.config.spec.dir))
+        return 'implement';
     if (!c.config.accept) {
         if (!l.warnings.includes(NO_ACCEPT))
             l.warnings.push(NO_ACCEPT);

package/dist/orchestrate/integrate.js

@@ -6,6 +6,7 @@ import { sharedStateDir } from '../state.js';
 import { releaseLock, takeLock } from './lock.js';
 import { mergeUnreleased, moveToUnreleased, settleLotEntries, unreleasedSections } from './changelog-merge.js';
 import { mutexFor } from './mutex.js';
+import { readPlanConfig } from '../config.js';
 import { Plan } from '../plan.js';
 import { parseDocument } from 'yaml';
 import { git, gitFailure, tryGit } from './worktree.js';
@@ -91,11 +92,15 @@ function resolvePlan(work) {
         return false;
     const file = files[0];
     try {
+        // Les champs d'extension déclarés (L464) sont des propriétés des lots : sans les réglages, `bare` ne verrait pas un champ changé.
+        // Seuls les champs d'extension sont passés : le `plan.onWrite` du projet ne doit pas se lancer pendant un rebase.
+        const extras = readPlanConfig(join(work, 'cadence.yaml'), work)?.settings.extras;
+        const settings = extras ? { extras } : {};
         const stage = (n) => {
             const text = run(work, 'show', `:${n}:${file}`);
             writeFileSync(join(work, file), text);
             const head = parseDocument(text).toJSON();
-            return { lots: Plan.load(join(work, file)).lots(), head: JSON.stringify({ ...(head ?? {}), lots: undefined }) };
+            return { lots: Plan.load(join(work, file), settings).lots(), head: JSON.stringify({ ...(head ?? {}), lots: undefined }) };
         };
         const [b, o, t] = [stage(1), stage(2), stage(3)];
         const [base, ours, theirs] = [b.lots, o.lots, t.lots];
@@ -109,7 +114,7 @@ function resolvePlan(work) {
         if (added.some((t) => review(ours.find((o) => o.id === t.id)) !== review(base.find((b) => b.id === t.id))))
             return false;
         writeFileSync(join(work, file), run(work, 'show', `:2:${file}`));
-        const plan = Plan.load(join(work, file));
+        const plan = Plan.load(join(work, file), settings);
         for (const t of added)
             plan.recordReview(t.id, t.review.verdict, t.review.date, t.review.commit ?? null, t.review.repos, t.review.reporte);
         plan.save();

package/dist/orchestrate/lot-budget.js

@@ -38,7 +38,7 @@ function ordinaryBasis(estimate, stage) {
     const basis = estimate <= 0.5 ? "plancher d'un lot jusqu'à 0,5 j" : estimate <= 1 ? "p90 mesuré du total d'un lot de 0,5 à 1 j" : Math.round(estimate * LOT_BUDGET_PER_DAY) <= LOT_BUDGET_ONE_DAY ? `plancher de ${LOT_BUDGET_ONE_DAY} au-delà d'un jour, l'estimate × ${LOT_BUDGET_PER_DAY} ne le dépasse pas encore` : `${LOT_BUDGET_PER_DAY} par jour, p90 mesuré du total au-delà d'un jour`;
     if (!stage)
         return basis;
-    return `${ordinary} dérivés de l'estimate (${basis}), plus ${SPEC_STAGE_ALLOCATION} pour les étapes spec, ${stage === 'screen' ? 'maquette' : 'fiche'} et accept`;
+    return `${ordinary} dérivés de l'estimate (${basis}), plus ${SPEC_STAGE_ALLOCATION} pour ${stage === 'light' ? 'les étapes spec et maquette' : `les étapes spec, ${stage === 'screen' ? 'maquette' : 'fiche'} et accept`}`;
 }
 /** Budget d'un lot, dérivé de son estimate et de sa catégorie : empêche quelques lots d'avaler le budget de la vague au détriment des autres. Un lot à `screen:` vaut le total mesuré d'un lot à écran (L194) ; un lot à `spec: true` y ajoute l'allocation de son étape (L191) ; `escalation` (orchestrate.escalation déclarée) y ajoute la part de l'escalade (L349). */
 export const lotBudget = (estimate, stage, escalation = false) => lotBaseBudget(estimate, stage) + (escalation ? ESCALATION_RESERVE : 0);
@@ -46,5 +46,5 @@ const lotBaseBudget = (estimate, stage) => {
     const ordinary = estimate <= 0.5 ? LOT_BUDGET_FLOOR : Math.max(LOT_BUDGET_ONE_DAY, Math.round(estimate * LOT_BUDGET_PER_DAY));
     if (stage === 'screen')
         return Math.max(SCREEN_LOT_BUDGET, ordinary + SPEC_STAGE_ALLOCATION);
-    return ordinary + (stage === 'spec' ? SPEC_STAGE_ALLOCATION : 0);
+    return ordinary + (stage === 'spec' || stage === 'light' ? SPEC_STAGE_ALLOCATION : 0);
 };

package/dist/orchestrate/maquette.js

@@ -15,6 +15,9 @@ export function maquetteText(o) {
             ? `This is review ${rank} of ${o.max}${rank >= o.max ? ', the last review' : ''}: the spec writer fixed the points of the previous one (below). Check them first, then run the whole sweep again and report ALL the blocking and major findings of it in this report. Mark \`inchange: true\` on every blocking or major finding about a point the spec writer did not change and the previous review had not raised.`
             : `This is the first review of this mockup (${o.max} review${o.max > 1 ? 's' : ''} at most): there is no later review to keep a finding for. Report ALL the blocking and major findings in this first report; do not keep one back for a later review.`,
     ];
+    if (o.light) {
+        lines.push(`Light mockup (L459): the sheet covers only the states the lot touches. Sweep those states only, at ${LARGEURS.join(' and ')} px, and compare the target of each one to the capture of the current screen \`${folder}/actuel-<état>-<largeur>.png\` (a free file, not checked by the program; when one is missing the spec writer said so under "nonVerifie": judge the target against the code and the neighbouring pages). Report what makes the target worse than the current screen or inconsistent with the rest of the application, not the defects of the screen the lot does not touch.`);
+    }
     if (later && o.previous?.length)
         lines.push('', 'Points of the previous review that the spec writer had to fix:', ...bulletLines(o.previous));
     return lines.join('\n');

package/dist/orchestrate/spec.js

@@ -4,6 +4,7 @@ import { join } from 'node:path';
 import { isMap, isNode, isScalar, isSeq, parse, parseDocument, stringify } from 'yaml';
 import { acceptationFile } from './accept.js';
 import { checkFiche, fichesDuDossier, LARGEURS } from '../spec.js';
+import { EXPRESS_MAX_ESTIMATE } from './express.js';
 const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
 const list = (v) => (Array.isArray(v) ? v.filter(isObj) : []);
 /** Chemin (relatif au dépôt) de la fiche du lot sous `<dir>/<écran ou sujet>/fiche.yaml` (`ecran.lot` ou `sujet.lot`), ou null : sert à ne pas rejouer une spec déjà écrite. */
@@ -24,6 +25,34 @@ export function specScreen(repo, dir, lot) {
     const entered = fichesDuDossier(repo, dir).some(({ name, doc }) => isObj(doc.ecran) && (doc.ecran.lot === lot.id || existsSync(join(repo, dir, name, acceptation))));
     return entered ? lot.screen : undefined;
 }
+/**
+ * Maquette légère (L459) : un lot visible, sans `spec: true`, d'estimate au-dessus de la retouche (voie express), dont le `screen:` du plan n'est pas `page`
+ * (`component`, `journey` ou absent) passe par spec → maquette avant le code, sans accept. Se déduit du plan à chaque appel, sans champ d'état :
+ * `orchestrate.maquette: false` la retire (la maquette légère est la revue de maquette, sans elle rien n'est à valider).
+ */
+export function lightMaquette(lot, maquette) {
+    return maquette && !!lot.visible && !lot.spec && typeof lot.estimate === 'number' && lot.estimate > EXPRESS_MAX_ESTIMATE && lot.screen !== 'page';
+}
+/**
+ * Le lot a une acceptation scellée (`acceptation-<lot>.json` à côté d'une fiche à bloc `ecran` de `dir`) : il est entré dans la chaîne complète
+ * avant L459 (spec → maquette → accept) et la garde, même s'il répond aujourd'hui à `lightMaquette` ; une maquette légère n'écrit jamais d'acceptation.
+ */
+export function sealedAcceptation(repo, dir, lot) {
+    const acceptation = acceptationFile('fiche.yaml', lot);
+    return fichesDuDossier(repo, dir).some(({ name, doc }) => isObj(doc.ecran) && existsSync(join(repo, dir, name, acceptation)));
+}
+/** Le lot est une maquette légère : son état a une étape spec (`screen` posé au lancement), son lot du plan répond à `lightMaquette` et il n'a pas d'acceptation scellée (`sealedAcceptation`). Relu du plan et du dépôt à chaque appel, aucun champ d'état. */
+export const lightLot = (state, lot, maquette, repo, dir) => !!state.screen && lightMaquette(lot, maquette) && !sealedAcceptation(repo, dir, lot.id);
+/** `screen` de l'état d'un lot à étape spec : celui de `specScreen`, ou, pour une maquette légère, celui du plan (`component` quand le plan n'en déclare pas : l'état ne sert alors qu'à dire « ce lot a une étape spec »). */
+export function stageScreen(repo, dir, lot, maquette) {
+    return specScreen(repo, dir, lot) ?? (lightMaquette(lot, maquette) ? (lot.screen ?? 'component') : undefined);
+}
+/** Catégorie de budget d'un lot (`lotBudget`) : `screen` pour un écran page, `light` pour une maquette légère, `spec` pour un lot `spec: true` sans écran. */
+export function budgetStage(lot, stateScreen, maquette, repo, dir) {
+    if (stateScreen)
+        return lightLot({ screen: stateScreen }, lot, maquette, repo, dir) ? 'light' : 'screen';
+    return lot.spec ? 'spec' : undefined;
+}
 /** Texte sans accents ni majuscules, pour les mots-clés. */
 const plain = (s) => s.normalize('NFD').replace(/[̀-ͯ]/g, '').toLowerCase();
 /**
@@ -267,20 +296,36 @@ export function hypothesisLines(doc) {
 }
 /** Texte de la note du lot pour une hypothèse (une note par règle). */
 export const hypothesisNote = (sujet, line) => `Hypothèses (fiche ${sujet}) — ${line}`;
+/** Consigne de rendu de la maquette : la commande que le projet déclare (`orchestrate.spec.render`), sinon Playwright. `use` : comment la reprendre. */
+const renderLine = (render, use) => render
+    ? `The project declares how to render mockups (\`orchestrate.spec.render\`): \`${render}\` (from the repository root). ${use}; fall back on Playwright only if it cannot run, and say so under "nonVerifie".`
+    : 'No render command is declared (`orchestrate.spec.render`): render with Playwright (open `maquette.html` as a local file, resize to each width, open each `#etat-<état>`).';
+/** Consigne de la maquette d'un lot `screen: page` (ou déjà entré dans la chaîne complète). */
+const pageLines = (o) => [
+    `The lot declares \`screen: ${o.screen}\`. The specs of this project live in \`${o.dir}/<écran>/\` (one folder per screen, \`<écran>\` = the kebab-case \`ecran.id\` of the sheet).`,
+    `Render each state of the mockup at ${LARGEURS.map((w) => `${w}`).join(' and ')} px width: one capture per state and per width, named \`maquette-<état>-<largeur>.png\` (e.g. \`maquette-vide-1440.png\`).`,
+    renderLine(o.render, 'Use it'),
+];
+/** Consigne de la maquette légère (L459) : l'écran actuel et la version visée des seuls états touchés. */
+const lightLines = (o) => [
+    `This lot is a visible lot that is not a whole page: write a light mockup, before any code. The specs of this project live in \`${o.dir}/<écran>/\` (one folder per screen, \`<écran>\` = the kebab-case \`ecran.id\` of the sheet).`,
+    'Cover only the states the lot touches (not the whole screen). For each touched state, capture the CURRENT screen of the application at each width, then the target version: the sheet and the mockup are limited to the states, fields and rules the lot changes.',
+    `Name the captures of the current screen \`actuel-<état>-<largeur>.png\` and those of the target \`maquette-<état>-<largeur>.png\`, one per touched state and per width (${LARGEURS.join(' and ')} px; e.g. \`actuel-vide-1440.png\`, \`maquette-vide-1440.png\`), in the folder of the sheet. The program checks the captures of the target, not the \`actuel-*\` ones.`,
+    'If the current screen cannot be captured (the application does not start, the page is protected), say so under "nonVerifie" and base the mockup on the code: never invent a capture of the current screen.',
+    'Each touched state is a section `id="etat-<état>"` of `maquette.html`, and each touched field carries a `data-testid`.',
+    renderLine(o.render, 'Use it for the target'),
+];
 /** Consigne propre à l'étape spec dans le brief : dossier, largeurs, commande de rendu, et les écarts de la passe précédente. */
 export function specText(o) {
     const lines = [];
-    if (o.screen) {
-        lines.push(`The lot declares \`screen: ${o.screen}\`. The specs of this project live in \`${o.dir}/<écran>/\` (one folder per screen, \`<écran>\` = the kebab-case \`ecran.id\` of the sheet).`, `Render each state of the mockup at ${LARGEURS.map((w) => `${w}`).join(' and ')} px width: one capture per state and per width, named \`maquette-<état>-<largeur>.png\` (e.g. \`maquette-vide-1440.png\`).`, o.render
-            ? `The project declares how to render mockups (\`orchestrate.spec.render\`): \`${o.render}\` (from the repository root). Use it; fall back on Playwright only if it cannot run, and say so under "nonVerifie".`
-            : 'No render command is declared (`orchestrate.spec.render`): render with Playwright (open `maquette.html` as a local file, resize to each width, open each `#etat-<état>`).');
-    }
+    if (o.screen)
+        lines.push(...(o.light ? lightLines(o) : pageLines(o)));
     if (o.back) {
         lines.push(o.screen
             ? `The sheet has both parts, \`sujet\`, \`cas\`, \`contrats\`, \`donnees\` next to \`ecran\`, in the same folder (\`sujet.id\` = \`ecran.id\` = the folder name, \`sujet.lot\` = \`ecran.lot\`); the API calls of the screen are listed once in \`contrats\`, and the actions point to them with \`contrat: Ax\`.`
             : `The lot declares \`spec: true\` (it changes a behaviour, with no screen). The specs of this project live in \`${o.dir}/<sujet>/\` (one folder per subject, \`<sujet>\` = the kebab-case \`sujet.id\` of the sheet); the sheet has no screen part.`);
     }
-    if (o.screen && !o.back) {
+    if (o.screen && !o.back && !o.light) {
         lines.push(`If the lot also changes a behaviour (an API call, a stored datum, a contract), add the back part to the same sheet: \`sujet\`, \`cas\`, \`contrats\`, \`donnees\` next to \`ecran\` (\`sujet.id\` = \`ecran.id\` = the folder name, \`sujet.lot\` = \`ecran.lot\`); the program then also has the sheet reviewed (rules sourced, contradictions, errors and limits, one test per rule), before the mockup. A lot that only draws a screen keeps a sheet without \`sujet\`.`);
     }
     if (o.template)

package/dist/plan-extras.js

@@ -0,0 +1,118 @@
+import { FIELDS, RafError } from './plan.js';
+const EXTRA_KEYS = ['enum', 'default'];
+const EXTRA_NAME = /^[a-z][a-z0-9_]*$/;
+/** Les clés que raf lit ou écrit sur un lot : un champ d'extension ne peut pas en prendre le nom. */
+const LOT_KEYS = ['tasks', 'uses', 'local', 'ux', 'review', 'docs_ok', 'extras', 'problems', 'state', 'state_before'];
+const nonEmptyText = (v) => typeof v === 'string' && v.trim() !== '';
+/** Une déclaration `plan.extras.<nom>` lue, ou l'erreur (message sans préfixe) qui la refuse. */
+function readDecl(name, decl) {
+    if (decl == null)
+        return {};
+    if (typeof decl !== 'object' || Array.isArray(decl))
+        return `extras.${name} doit être un objet { enum, default }`;
+    const d = decl;
+    const unknown = Object.keys(d).find((k) => !EXTRA_KEYS.includes(k));
+    if (unknown)
+        return `extras.${name}.${unknown} inconnu (attendu : ${EXTRA_KEYS.join(', ')})`;
+    const out = {};
+    if (d.enum != null) {
+        if (!Array.isArray(d.enum) || d.enum.length === 0 || !d.enum.every(nonEmptyText))
+            return `extras.${name}.enum doit être une liste non vide de textes`;
+        if (new Set(d.enum).size !== d.enum.length)
+            return `extras.${name}.enum : une valeur est donnée deux fois`;
+        out.enum = d.enum;
+    }
+    if (d.default != null) {
+        if (!nonEmptyText(d.default))
+            return `extras.${name}.default doit être un texte non vide`;
+        if (out.enum && !out.enum.includes(d.default))
+            return `extras.${name}.default « ${d.default} » hors de enum (${out.enum.join(', ')})`;
+        out.default = d.default;
+    }
+    return out;
+}
+/**
+ * Clé `plan.extras` de cadence.yaml (L464) lue en `{ extras }` (`{}` quand la clé manque). Refuse, en nommant la clé : une forme fausse, un nom invalide ou pris
+ * par un champ de raf, un plan tenu par un autre outil (`foreign` : lecture seule, raf n'y écrit aucun champ).
+ */
+export function readExtras(v, foreign, bad) {
+    if (v == null)
+        return {};
+    if (foreign)
+        throw bad("extras ne s'applique pas à un plan tenu par un autre outil (lecture seule)");
+    if (typeof v !== 'object' || Array.isArray(v))
+        throw bad('extras doit être un objet { champ: { enum, default } }');
+    const extras = {};
+    for (const [name, raw] of Object.entries(v)) {
+        if (!EXTRA_NAME.test(name))
+            throw bad(`extras.${name} : nom invalide (minuscules, chiffres et _, commençant par une lettre)`);
+        if (FIELDS.includes(name) || LOT_KEYS.includes(name))
+            throw bad(`extras.${name} : c'est un champ de raf, pas un champ d'extension`);
+        const decl = readDecl(name, raw);
+        if (typeof decl === 'string')
+            throw bad(decl);
+        extras[name] = decl;
+    }
+    return { extras };
+}
+/** Ce qui cloche dans la valeur d'un champ d'extension, ou null : champ non déclaré, pas un texte non vide, hors de `enum`. */
+function valueProblem(decls, name, value) {
+    const decl = decls[name];
+    if (!decl) {
+        const names = Object.keys(decls);
+        return names.length === 0 ? `${name} : aucun champ d'extension déclaré (cadence.yaml : plan.extras)` : `${name} : champ d'extension non déclaré (${names.join(', ')})`;
+    }
+    if (!nonEmptyText(value))
+        return `${name} : texte non vide attendu`;
+    if (decl.enum && !decl.enum.includes(value.trim()))
+        return `${name} « ${value.trim()} » hors de enum (${decl.enum.join(', ')})`;
+    return null;
+}
+/** Les champs à poser à la création d'un lot (`raf add --set`), validés et nettoyés ; une erreur refuse tout. Sans valeur donnée : rien. */
+export function checkedExtras(decls, given) {
+    const out = {};
+    for (const [name, value] of Object.entries(given ?? {})) {
+        const problem = valueProblem(decls ?? {}, name, value);
+        if (problem)
+            throw new RafError(problem);
+        out[name] = value.trim();
+    }
+    return out;
+}
+/**
+ * Le lot lu avec ses champs d'extension : la valeur écrite, sinon le `default`. Une valeur fausse est remontée par check (`bad-field`) et n'est pas gardée.
+ * Les clés non déclarées ne sont pas lues : elles restent sur le disque, intactes.
+ */
+export function withExtras(lot, raw, decls) {
+    const extras = {};
+    for (const [name, decl] of Object.entries(decls ?? {})) {
+        const written = raw[name];
+        if (written == null) {
+            if (decl.default !== undefined)
+                extras[name] = decl.default;
+            continue;
+        }
+        const problem = valueProblem(decls ?? {}, name, written);
+        if (problem)
+            lot.problems.push(problem);
+        else
+            extras[name] = written.trim();
+    }
+    return Object.keys(extras).length > 0 ? { ...lot, extras } : lot;
+}
+/** Les `--set champ=valeur` de `raf add` : champ → valeur, coupée au premier « = ». Une forme sans champ ou sans valeur, un champ donné deux fois : refusés. Rend undefined sans `--set`. */
+export function parseSet(sets) {
+    if (sets === undefined)
+        return undefined;
+    const out = {};
+    for (const item of sets) {
+        const [name, ...rest] = item.split('=');
+        const value = rest.join('=').trim();
+        if (name.trim() === '' || value === '')
+            throw new RafError(`--set attend champ=valeur (reçu « ${item} »)`);
+        if (Object.hasOwn(out, name.trim()))
+            throw new RafError(`--set ${name.trim()} est donné deux fois`);
+        out[name.trim()] = value;
+    }
+    return out;
+}

package/dist/plan-read.js

@@ -0,0 +1,144 @@
+import { isDay } from './dates.js';
+import { RESOURCE_NAME, RESOURCES_BAD_LIST, SCREENS, STATUSES } from './plan.js';
+const GATE_INVALID = 'gate invalide : count: entier ≥ 1 et un critère spec: true ou screen: page attendus';
+/** Lit `gate: { count: N, spec: true }` ou `{ count: N, screen: page }` ; toute autre forme est un problème du lot et une condition jamais remplie. */
+function readGate(raw, problems) {
+    if (raw == null)
+        return undefined;
+    const invalid = () => {
+        problems.push(GATE_INVALID);
+        return { invalid: true };
+    };
+    if (typeof raw !== 'object' || Array.isArray(raw))
+        return invalid();
+    const g = raw;
+    if (!Number.isInteger(g.count) || g.count < 1)
+        return invalid();
+    const criteria = [...(g.spec === true ? ['spec'] : []), ...(g.screen === 'page' ? ['screen'] : [])];
+    const others = Object.keys(g).filter((k) => k !== 'count' && k !== 'spec' && k !== 'screen');
+    if (criteria.length !== 1 || others.length || ('spec' in g && g.spec !== true) || ('screen' in g && g.screen !== 'page'))
+        return invalid();
+    return { count: g.count, criterion: criteria[0] };
+}
+/** `state:` et `state_before:` écrits à la main avec un non-texte : signalés, la clé étant écartée. */
+function checkStateNames(raw, problems) {
+    for (const k of ['state', 'state_before'])
+        if (raw[k] != null && typeof raw[k] !== 'string')
+            problems.push(`${k} : un nom d'état attendu (reçu « ${String(raw[k])} »)`);
+}
+export function normalizeLot(raw, problems = []) {
+    const status = STATUSES.includes(raw.status) ? raw.status : 'todo';
+    const asDay = (field) => {
+        const v = raw[field];
+        if (v == null)
+            return undefined;
+        if (isDay(v))
+            return v;
+        problems.push(`${field} « ${String(v)} » n'est pas une date AAAA-MM-JJ`);
+        return undefined;
+    };
+    const after = raw.after == null ? [] : Array.isArray(raw.after) ? raw.after.map(String) : [String(raw.after)];
+    const last = asDay('last');
+    let uses;
+    if (raw.uses != null) {
+        if (Array.isArray(raw.uses) && raw.uses.every((n) => typeof n === 'string' && RESOURCE_NAME.test(n)))
+            uses = [...new Set(raw.uses)];
+        else
+            problems.push(`uses ${RESOURCES_BAD_LIST}`);
+    }
+    let screen;
+    if (raw.screen != null) {
+        if (SCREENS.includes(raw.screen))
+            screen = raw.screen;
+        else
+            problems.push(`screen « ${String(raw.screen)} » inconnu (${SCREENS.join(', ')})`);
+        if (screen && raw.visible !== true)
+            problems.push(`screen « ${screen} » sans visible : un écran est un changement visible`);
+    }
+    let spec;
+    if (raw.spec != null) {
+        if (raw.spec === true)
+            spec = true;
+        else if (raw.spec !== false)
+            problems.push(`spec : true ou false attendu (reçu « ${String(raw.spec)} »)`);
+    }
+    checkStateNames(raw, problems);
+    const gate = readGate(raw.gate, problems);
+    const okRaw = raw.docs_ok;
+    const docsOk = okRaw && typeof okRaw === 'object' && typeof okRaw.reason === 'string' && okRaw.reason.trim() !== '' ? { date: String(okRaw.date ?? ''), reason: okRaw.reason.trim() } : undefined;
+    return {
+        id: String(raw.id),
+        title: String(raw.title ?? ''),
+        status,
+        ...(typeof raw.state === 'string' && raw.state.trim() !== '' ? { state: raw.state.trim() } : {}),
+        ...(typeof raw.state_before === 'string' && raw.state_before.trim() !== '' ? { stateBefore: raw.state_before.trim() } : {}),
+        estimate: typeof raw.estimate === 'number' && raw.estimate > 0 ? raw.estimate : 1,
+        quickwin: raw.quickwin === true,
+        visible: raw.visible === true,
+        ...(screen ? { screen } : {}),
+        ...(spec ? { spec } : {}), ...(raw.local === true ? { local: true } : {}),
+        ...(gate ? { gate } : {}),
+        ...(typeof raw.public === 'string' && raw.public.trim() !== '' ? { public: raw.public.trim() } : {}),
+        ...(typeof raw.goal === 'string' && raw.goal.trim() !== '' ? { goal: raw.goal.trim() } : {}),
+        ...(Number.isInteger(raw.every) && raw.every > 0 ? { every: raw.every } : {}),
+        ...(last ? { last } : {}),
+        after,
+        ...(uses?.length ? { uses } : {}),
+        created: asDay('created'),
+        started: asDay('started'),
+        finished: asDay('finished'),
+        notes: Array.isArray(raw.notes)
+            ? raw.notes.map((n) => ({ date: String(n.date ?? ''), text: String(n.text ?? '') }))
+            : [],
+        tasks: Array.isArray(raw.tasks)
+            ? raw.tasks.map((t) => ({
+                id: String(t.id),
+                title: String(t.title ?? ''),
+                status: STATUSES.includes(t.status) ? t.status : 'todo',
+            }))
+            : [],
+        ...(repoList(raw.repos).length ? { repos: repoList(raw.repos) } : {}),
+        ...(asVerdict(raw.ux) ? { ux: asVerdict(raw.ux) } : {}),
+        ...(asVerdict(raw.review) ? { review: asVerdict(raw.review) } : {}),
+        ...(docsOk ? { docsOk } : {}),
+        problems,
+    };
+}
+/**
+ * Dépôts voisins déclarés : une chaîne (le chemin) ou un objet `{ path, cite }`, seuls ou en liste (une valeur seule vaut une
+ * liste d'un dépôt). Une entrée sans chemin textuel est écartée ; un `cite` vide ou non textuel vaut pas de `cite`.
+ */
+function repoList(raw) {
+    const items = Array.isArray(raw) ? raw : raw == null ? [] : [raw];
+    const out = [];
+    for (const item of items) {
+        const path = typeof item === 'string' ? item : item && typeof item === 'object' && typeof item.path === 'string' ? item.path : '';
+        if (path.trim() === '')
+            continue;
+        const cite = item && typeof item === 'object' ? item.cite : undefined;
+        out.push({ path: path.trim(), ...(typeof cite === 'string' && cite.trim() !== '' ? { cite: cite.trim() } : {}) });
+    }
+    return out;
+}
+function asVerdict(raw) {
+    if (!raw || typeof raw !== 'object')
+        return undefined;
+    const v = raw;
+    // Écrit à la main sans verdict (clé absente, vide ou blanche) : rien n'a été dit de la revue, la porte
+    // reste fermée — comme `raf ux` et `raf review` refusent d'enregistrer un verdict vide.
+    if (String(v.verdict ?? '').trim() === '')
+        return undefined;
+    const verdict = { date: String(v.date ?? ''), verdict: String(v.verdict) };
+    // Champ présent mais vide : relu « jusqu'à rien », comme un verdict noté sans commit.
+    if ('commit' in v)
+        verdict.commit = v.commit == null || String(v.commit).trim() === '' ? null : String(v.commit).trim();
+    if (v.repos && typeof v.repos === 'object' && !Array.isArray(v.repos)) {
+        const repos = Object.entries(v.repos).map(([k, sha]) => [k, sha == null || String(sha).trim() === '' ? null : String(sha).trim()]);
+        if (repos.length)
+            verdict.repos = Object.fromEntries(repos);
+    }
+    const r = v.reporte;
+    if (r && typeof r === 'object' && !Array.isArray(r) && r.de != null && r.vers != null)
+        verdict.reporte = { de: String(r.de), vers: String(r.vers), patchId: String(r.patchId ?? '') };
+    return verdict;
+}

package/dist/plan-states.js

@@ -0,0 +1,119 @@
+import { isObject, list } from './yaml-keys.js';
+import { STATUSES } from './plan.js';
+function parseBases(raw, bad) {
+    if (!isObject(raw))
+        throw bad('states doit être un objet { état: statut de base }');
+    const states = {};
+    for (const [name, base] of Object.entries(raw)) {
+        if (!STATUSES.includes(base))
+            throw bad(`states.${name} : statut de base « ${String(base)} » inconnu (attendu : ${STATUSES.join(', ')})`);
+        states[name] = base;
+    }
+    const bases = Object.values(states);
+    if (!['todo', 'doing', 'done'].every((b) => bases.includes(b)))
+        throw bad('states doit déclarer au moins un état todo, un doing et un done');
+    return states;
+}
+function parseTransitions(raw, states, bad) {
+    if (!isObject(raw))
+        throw bad('transitions doit être un objet { état: [états permis] }');
+    const transitions = {};
+    for (const [from, tos] of Object.entries(raw)) {
+        if (!Object.hasOwn(states, from))
+            throw bad(`transitions : « ${from} » n'est pas un état déclaré`);
+        for (const to of list(tos))
+            if (!Object.hasOwn(states, to))
+                throw bad(`transitions.${from} : « ${to} » n'est pas un état déclaré`);
+        transitions[from] = list(tos);
+    }
+    return transitions;
+}
+function requireNames(p, bad) {
+    for (const k of ['doneState', 'blockedState'])
+        if (p[k] != null && typeof p[k] !== 'string')
+            throw bad(`${k} : un nom d'état attendu`);
+}
+/**
+ * Lit `plan.states`, `plan.transitions`, `plan.doneState` et `plan.blockedState` de cadence.yaml : `{ states }` ou `{}` quand rien n'est déclaré.
+ * `foreign` : le plan est tenu par un autre outil (lots, fields, statuses, estimates), dont les états sont les siens.
+ */
+export function parseStates(p, bad, foreign) {
+    if (p.states == null) {
+        for (const k of ['transitions', 'doneState', 'blockedState'])
+            if (p[k] != null)
+                throw bad(`${k} demande plan.states`);
+        return {};
+    }
+    if (foreign)
+        throw bad('states ne va pas avec un plan tenu par un autre outil (lots, fields, statuses, estimates) : ses états sont les siens');
+    const states = parseBases(p.states, bad);
+    const model = { states };
+    if (p.transitions != null)
+        model.transitions = parseTransitions(p.transitions, states, bad);
+    requireNames(p, bad);
+    if (p.doneState != null) {
+        if (states[String(p.doneState)] !== 'done')
+            throw bad(`doneState : « ${String(p.doneState)} » n'est pas un état done`);
+        model.done = String(p.doneState);
+    }
+    if (p.blockedState != null) {
+        const base = states[String(p.blockedState)];
+        if (base !== 'todo' && base !== 'doing')
+            throw bad(`blockedState : « ${String(p.blockedState)} » doit être un état todo ou doing`);
+        model.blocked = String(p.blockedState);
+    }
+    return { states: model };
+}
+/** L'état que prend un lot qui entre dans ce statut de base : `doneState` pour done, sinon le premier état déclaré de ce statut. */
+export function defaultState(model, base) {
+    if (base === 'done' && model.done)
+        return model.done;
+    return Object.keys(model.states).find((s) => model.states[s] === base);
+}
+/** L'état d'un lot : celui qu'il porte, sinon l'état par défaut de son statut (lot écrit avant la déclaration). */
+export function currentState(model, lot) {
+    return lot.state ?? defaultState(model, lot.status) ?? lot.status;
+}
+/** Pourquoi `from → to` est refusé par `plan.transitions` ; `null` quand c'est permis ou que rien n'est déclaré. */
+export function transitionProblem(model, from, to) {
+    if (!model.transitions)
+        return null;
+    const allowed = model.transitions[from];
+    if (allowed?.includes(to))
+        return null;
+    return `${from} → ${to} n'est pas permis (${allowed?.length ? `depuis ${from} : ${allowed.join(', ')}` : 'état terminal'})`;
+}
+/** Les écarts d'un état écrit à la main : état non déclaré, ou statut de base qui contredit `status:`. */
+export function stateProblems(model, lot) {
+    if (lot.state === undefined)
+        return [];
+    const base = Object.hasOwn(model.states, lot.state) ? model.states[lot.state] : undefined;
+    if (base === undefined)
+        return [`état « ${lot.state} » non déclaré (cadence.yaml : plan.states)`];
+    return base === lot.status ? [] : [`état « ${lot.state} » (${base}) contredit status: ${lot.status}`];
+}
+/**
+ * Applique à `node` le changement de statut de base de `raf status` : todo → doing démarre le lot, doing → todo le remet en attente
+ * (`started:` retiré) — refusé, comme `raf todo`, dès qu'un commit cite le lot : le remettre en attente perdrait leur lien. Rend le refus
+ * (`move` nomme le lot, l'état visé et son statut de base), `undefined` quand le changement est fait. Autre changement : rien n'est touché,
+ * le refus renvoie à sa commande.
+ */
+export function rebase(node, lot, move, today, commits) {
+    const { ref, to, base } = move;
+    if (lot.status === 'todo' && base === 'doing') {
+        node.set('status', 'doing');
+        if (!lot.started)
+            node.set('started', today);
+        return undefined;
+    }
+    if (lot.status === 'doing' && base === 'todo') {
+        const n = commits();
+        if (n > 0)
+            return `${ref} a ${n} commit(s) qui le citent : le remettre en attente perdrait leur lien — un état doing (raf status ${ref} <état>), ou raf drop ${ref}`;
+        node.set('status', 'todo');
+        node.delete('started');
+        return undefined;
+    }
+    const command = base === 'done' ? 'done' : base === 'dropped' ? 'drop' : 'todo';
+    return `${ref} : ${to} a pour statut de base ${base}, ${lot.status} aujourd'hui — passer par raf ${command} ${ref}`;
+}