@sylad/cadence 1.4.0 → 1.6.0

package/dist/orchestrate/cycle.js

@@ -450,13 +450,14 @@ function briefFor(c, kind) {
         const reviewed = [...(l.ficheConstats ?? []), ...(l.maquetteConstats ?? [])];
         const written = ficheOf(c);
         const back = partsOf(l, written).back;
+        const session = { run: (l.specRuns ?? 0) + 1, max: specBudget(c) };
         vars.spec = specText({
             dir: c.config.spec.dir,
             render: c.config.spec.render,
             screen: l.screen,
             back,
             problems: l.specProblems,
-            review: !reviewed.length ? undefined : back ? reviewedSheetText(reviewed, !!l.screen) : reviewedText(reviewed),
+            review: !reviewed.length ? undefined : back ? reviewedSheetText(reviewed, !!l.screen, session) : reviewedText(reviewed, session),
             template: l.screen ? ficheTemplate() : undefined,
             templateBack: back || l.screen ? ficheBackTemplate() : undefined,
         });
@@ -471,7 +472,7 @@ function briefFor(c, kind) {
         vars.reponse = '';
     }
     if (kind === 'maquette') {
-        vars.maquette = maquetteText({ fiche: ficheOf(c) ?? '', passes: l.maquette?.passes ?? 0, previous: l.maquetteConstats });
+        vars.maquette = maquetteText({ fiche: ficheOf(c) ?? '', passes: l.maquette?.passes ?? 0, max: c.config.maquetteReviews, previous: l.maquetteConstats });
         vars.reponse = '';
     }
     if (kind === 'accept') {
@@ -517,6 +518,20 @@ const lotOver = (l) => l.budget !== undefined && lotSpent(l) >= l.budget;
  * alors être refusée et le lot revient au lead sans revue, avec ses constats.
  */
 export const REVIEW_RESERVE = 155_000;
+/** Étapes d'écriture : les seules que le budget du lot borne (`session`), donc les seules qu'il puisse laisser non jouées. */
+const WRITE_STEPS = ['implement', 'fix', 'spec', 'accept'];
+/**
+ * Étape d'écriture que le budget a laissée non jouée (L223), pour un lot rendu au lead sur budget ; null sinon. `stop` vide `next` : l'étape se lit
+ * dans l'outcome que `overBudget` écrit (« étape « fix » non jouée »), repli sur `next` s'il est resté. Reconnu par ce texte (aucun marqueur dans
+ * l'état) : « correction non jouée (budget) » ou « budget du lot atteint ».
+ */
+export function budgetStep(l) {
+    if (l.status !== 'handed-back' || !/correction non jouée \(budget\)|budget du lot atteint/.test(l.outcome ?? ''))
+        return null;
+    const named = /étape « ([\w-]+) » non jouée/.exec(l.outcome ?? '')?.[1];
+    const step = named ?? l.next;
+    return step && WRITE_STEPS.includes(step) ? step : null;
+}
 /** Le budget du lot paie-t-il la passe de correction et la revue courte qui la suit ? Sans budget de lot : toujours. */
 const fixAffordable = (l) => l.budget === undefined || lotSpent(l) + REVIEW_RESERVE < l.budget;
 /** Cause d'une suspension demandée par `--stop-after-current` (L79). */
@@ -1112,6 +1127,8 @@ function takeReport(c, done, rep) {
             l.warnings.push(`question ignorée (non-question) : « ${q.trim()} »`);
     return rep.questions.filter((q) => !isNonQuestion(q));
 }
+/** Plafond de sessions `spec` du lot (L230) : les revues de maquette d'un lot à écran, sinon deux. Fiche et maquette partagent `l.specRuns`. */
+const specBudget = (c) => (c.lot.screen && c.config.maquette ? c.config.maquetteReviews : 2);
 /**
  * Étape spec (L171, spec etape-spec S3) : la session écrit maquette, captures et fiche dans `<spec.dir>/<écran>/`, le programme
  * en relève les écarts (une seconde passe, puis le lot est rendu), une hypothèse coûteuse à défaire devient une question au lead,
@@ -1134,7 +1151,7 @@ async function specStep(c) {
     const questions = takeReport(c, done, rep);
     if (questions.length) {
         l.questions = questions;
-        l.specRuns = undefined; // la réponse ouvre un nouveau budget de deux sessions
+        l.specRuns = undefined; // la réponse ouvre un nouveau budget de sessions
         l.specAsked = undefined; // la prochaine réponse porte sur la question de la session, pas sur d'anciennes hypothèses coûteuses
         l.next = 'spec';
         transition(c, 'question', questions[0]);
@@ -1163,8 +1180,8 @@ async function specStep(c) {
     const inDir = fiche === '' || fiche.startsWith(`${c.config.spec.dir.replace(/\/+$/, '')}/`);
     const problems = !outside && fiche && !inDir ? [`${fiche} : fiche hors de ${c.config.spec.dir} (la spec vit dans ${c.config.spec.dir}/${what}/fiche.yaml, où l'étape la retrouve)`] : outside ? [`${reported} : fiche hors du dépôt (le chemin de « fiche » est relatif au dépôt : ${c.config.spec.dir}/${what}/fiche.yaml)`] : fiche ? checkSpec(l.repo, fiche, l.lot, partsOf(l, fiche)) : [`aucune fiche écrite : ${c.config.spec.dir}/${what}/fiche.yaml est attendue (ou une raison dans « sousSeuil » si le lot ne change ${l.screen ? 'aucun écran' : 'aucun comportement'})`];
     if (problems.length) {
-        if ((l.specRuns ?? 0) >= 2) {
-            stop(c, 'handed-back', `spec non conforme après 2 passes : ${problems.join(' ; ')}`);
+        if ((l.specRuns ?? 0) >= specBudget(c)) {
+            stop(c, 'handed-back', `spec non conforme après ${specBudget(c)} passes : ${problems.join(' ; ')}`);
             return;
         }
         l.specProblems = problems;
@@ -1179,7 +1196,7 @@ async function specStep(c) {
     if (costly.length) {
         l.questions = costly.map((x) => `${x.id} est posée comme hypothèse mais touche un choix coûteux à défaire (${x.categorie}) : « ${x.siFaux} » — la confirmer, ou la corriger, avant que la fiche serve de référence.`);
         l.specAsked = [...l.questions];
-        l.specRuns = undefined; // la réponse du lead ouvre un nouveau budget de deux sessions, comme celle d'une question de la session
+        l.specRuns = undefined; // la réponse du lead ouvre un nouveau budget de sessions, comme celle d'une question de la session
         l.next = 'spec';
         transition(c, 'question', l.questions[0]);
         return;
@@ -1280,8 +1297,8 @@ async function noteMinors(c, rep, label) {
 const FICHE_REVIEW = { kind: 'fiche', label: 'fiche', source: 'code', after: afterFiche, retry: afterFiche };
 const MAQUETTE_REVIEW = { kind: 'maquette', label: 'maquette', source: 'ux', after: afterMaquette, retry: () => 'spec' };
 /**
- * Revue de la spec (fiche ou maquette) : une session de lecture seule. Un bloquant ou un majeur renvoie à la spec (une seule seconde passe, avec
- * les constats ; pour un lot mixte, ceux des deux revues ensemble), puis la spec est relue ; ce qui reste après la seconde revue est rendu au lead.
+ * Revue de la spec (fiche ou maquette) : une session de lecture seule. Un bloquant ou un majeur renvoie à la spec (avec les constats ; pour un lot mixte, ceux des deux revues ensemble), puis la spec est relue : deux revues pour la fiche,
+ * `orchestrate.maquetteReviews` pour la maquette, dans le plafond de sessions spec du lot (`specBudget`) ; ce qui reste à la dernière revue est rendu au lead.
  * Les mineurs de la fiche vont en notes du lot (ceux de la maquette restent des propositions). Ce verdict n'est pas `raf review` ni `raf ux` : la revue après code garde ce rôle.
  */
 async function reviewSpecStep(c, r) {
@@ -1312,6 +1329,12 @@ async function reviewSpecStep(c, r) {
     if (r.kind === 'fiche' && (await noteMinors(c, rep, `la ${r.label}`)))
         return;
     const constats = blockingConstats(rep, r.source);
+    if (r.kind === 'maquette' && passes >= 2) {
+        // Lu sur rep.constats : blockingConstats ne garde pas `inchange`. Seul le booléen vrai est une marque (checkShape ne descend pas dans constats[]).
+        for (const k of rep.constats)
+            if ((k.gravite === 'bloquant' || k.gravite === 'majeur') && k.inchange === true)
+                c.wave.log(`${lotKey(l.project, l.lot)} · défaut de revue : maquette, revue ${passes}, majeur sur un point inchangé absent de la revue ${passes - 1} : ${k.texte}`);
+    }
     const key = r.kind === 'fiche' ? 'ficheConstats' : 'maquetteConstats';
     if (summary.conforme) {
         l[key] = undefined;
@@ -1319,13 +1342,14 @@ async function reviewSpecStep(c, r) {
         save(c);
         return;
     }
-    if (passes >= 2) {
-        stop(c, 'handed-back', `${r.label} non conforme après 2 revues : ${summary.verdict}\n${bulletLines(constats).join('\n')}`);
+    const reviews = r.kind === 'maquette' ? c.config.maquetteReviews : 2;
+    if (passes >= reviews) {
+        stop(c, 'handed-back', `${r.label} non conforme après ${reviews} revue${reviews > 1 ? 's' : ''} : ${summary.verdict}\n${bulletLines(constats).join('\n')}`);
         return;
     }
-    // Le budget de deux sessions spec est épuisé (écarts du programme compris) : un renvoi à la spec serait une 3ᵉ session.
-    if ((l.specRuns ?? 0) >= 2) {
-        stop(c, 'handed-back', `${r.label} non conforme et la spec a déjà joué 2 sessions : ${summary.verdict}\n${bulletLines(constats).join('\n')}`);
+    // Le budget de sessions spec est épuisé (écarts du programme compris) : un renvoi à la spec serait une session de trop.
+    if ((l.specRuns ?? 0) >= specBudget(c)) {
+        stop(c, 'handed-back', `${r.label} non conforme et la spec a déjà joué ${specBudget(c)} sessions : ${summary.verdict}\n${bulletLines(constats).join('\n')}`);
         return;
     }
     l[key] = constats.length ? constats : [{ source: r.source, gravite: 'majeur', texte: summary.verdict }];
@@ -1476,6 +1500,12 @@ async function work(c, kind) {
         badReport(c, done.step, e);
         return;
     }
+    // L'écriture a changé le code (L221) : le verdict et les constats de la revue UX d'avant ne valent plus, l'UX est rejouée après la prochaine revue de code conforme.
+    if (!l.small) {
+        l.ux = undefined;
+        l.uxVerdict = null;
+        l.constats = l.constats.filter((k) => k.source !== 'ux');
+    }
     const plan = c.loadPlan();
     const range = done.step.headBefore ? `${done.step.headBefore}..HEAD` : undefined;
     const commits = readCommits(l.repo, { range });
@@ -1552,7 +1582,12 @@ async function work(c, kind) {
             propose(c, minorLine('code', k));
         l.constats = [];
         l.warnings.push('passe des mineurs sans commit : le lot conclut sur la revue conforme d\'origine, mineurs rendus en propositions');
-        if (l.code)
+        if (l.code && uxAfterReview(c)) {
+            // L221 : l'UX finale suit la dernière revue de code conforme, y compris quand la passe des mineurs n'a rien commité.
+            l.next = 'ux';
+            save(c);
+        }
+        else if (l.code)
             await conclude(c, l.code, ' sans commit');
         else
             stop(c, 'handed-back', 'passe des mineurs sans commit, mais aucune revue conforme gardée');
@@ -1637,25 +1672,24 @@ async function work(c, kind) {
     l.next = firstReview(c);
     save(c);
 }
+/** Mention « sans commit » du verdict quand la passe des mineurs n'a rien commité (l'UX finale conclut alors à la place de la passe). */
+const noCommitNote = (l) => (l.warnings.some((w) => w.startsWith('passe des mineurs sans commit')) ? ' sans commit' : '');
 /** Revue de code qui clôt le cycle : complète, ou courte une fois la passe des mineurs jouée. */
 const codeReview = (l) => (l.minorPass ? 'review-small' : 'review');
 /**
- * Première étape après un travail d'écriture. Le code vient de changer : l'UX d'un lot visible est donc toujours rejouée
- * (une revue antérieure serait périmée), puis une revue de code clôt le cycle.
+ * Première étape après un travail d'écriture (L221) : la revue de code, jamais l'UX. La revue UX d'un lot visible est jouée une seule fois,
+ * après la dernière revue de code conforme (`uxAfterReview`), sur le code qui sera livré.
  */
 function firstReview(c) {
     const l = c.lot;
     if (l.small)
         return l.visible || l.minorPass ? 'review-small' : 'review'; // passe unique code + ergonomie ; sans écran, une revue de code
-    if (l.visible) {
-        if (!c.config.ux) {
-            l.uxNote = 'UX à faire par le lead (aucune application déclarée : cadence.yaml orchestrate.ux)';
-            return codeReview(l);
-        }
-        return 'ux';
-    }
+    if (l.visible && !c.config.ux)
+        l.uxNote = 'UX à faire par le lead (aucune application déclarée : cadence.yaml orchestrate.ux)';
     return codeReview(l);
 }
+/** La revue de code conforme d'un lot visible non petit est-elle suivie de la revue UX ? Sans `orchestrate.ux`, le lot conclut (note « UX à faire par le lead »). */
+const uxAfterReview = (c) => !c.lot.small && c.lot.visible && !!c.config.ux;
 /** Une passe de correction de plus, ou la main rendue au lead quand les deux sont faites. */
 function toFix(c, constats, what) {
     const l = c.lot;
@@ -1677,12 +1711,20 @@ const seesApp = (l, kind) => kind === 'ux' || (kind === 'review-small' && l.smal
 const appNote = (state, ux) => state.kind === 'busy' ? `UX non vérifiée : port occupé (${ux.url} répond déjà, l'application n'a pas été lancée)` : state.kind === 'unverified' ? `UX non vérifiée : ${state.cause}` : '';
 /**
  * Avec `command` ET `url`, le programme lance l'application avant l'étape et la tue après (succès, erreur ou signal) :
- * port occupé ou application muette, la revue UX n'a pas lieu (note dans le lot, la revue de code suit) ; la passe
- * unique d'un petit lot, elle, a lieu sur le code seul.
+ * port occupé ou application muette, la revue UX n'a pas lieu (étape `skipped`, note dans le lot) et le lot conclut
+ * sur la dernière revue de code conforme (R6) ; la passe unique d'un petit lot, elle, a lieu sur le code seul.
  */
 async function review(c, kind) {
     const l = c.lot;
     const ux = c.config.ux;
+    // Un état repris, écrit avant L221, peut porter next = ux : l'UX ne part que sur une revue de code conforme du HEAD courant, sinon la revue de code passe d'abord (R9).
+    if (kind === 'ux' && !(l.code?.conforme && l.code.head === git(l.repo, 'rev-parse', 'HEAD'))) {
+        l.next = codeReview(l);
+        if (l.status === 'suspended')
+            l.status = 'reviewing'; // reprise d'un lot suspendu : la boucle de runLot enchaîne sur la revue de code au lieu de rendre la main
+        save(c);
+        return;
+    }
     if (!ux?.command || !ux.url || !seesApp(l, kind))
         return reviewStep(c, kind);
     const halt = halted(c.wave, l);
@@ -1690,6 +1732,7 @@ async function review(c, kind) {
         suspend(c, halt); // la session n'aurait pas lieu : l'application ne se lance pas pour rien
         return;
     }
+    let skipped = false;
     c.wave.log(`${lotKey(l.project, l.lot)} · lancement de l'application (${ux.url})`);
     const app = await startApp({ command: ux.command, url: ux.url, cwd: l.repo, nodeBin: l.node?.link, log: join(c.wave.store.lotDir(l.project, l.lot), 'ux-app.log'), timeoutMs: (ux.timeout ?? APP_TIMEOUT_S) * 1000 });
     try {
@@ -1698,12 +1741,7 @@ async function review(c, kind) {
             l.uxNote = appNote(app.state, ux);
             c.wave.log(`${lotKey(l.project, l.lot)} · ${l.uxNote.split('\n')[0]}`);
             if (kind === 'ux') {
-                // Aucune session : une revue UX antérieure, périmée par le code qui a changé, ne pèse plus.
-                l.ux = undefined;
-                l.uxVerdict = null;
-                l.constats = l.constats.filter((k) => k.source !== 'ux');
-                l.next = codeReview(l);
-                save(c);
+                skipped = true; // aucune session : la revue de code conforme suffit, le lot conclut avec la note
                 return;
             }
         }
@@ -1714,6 +1752,8 @@ async function review(c, kind) {
     finally {
         c.app = undefined;
         await app.stop();
+        if (skipped && l.code)
+            await conclude(c, l.code, noCommitNote(l));
     }
 }
 async function reviewStep(c, kind) {
@@ -1735,8 +1775,12 @@ async function reviewStep(c, kind) {
         addProposals(c, rep, 'ux');
         l.uxVerdict = summary.verdict;
         l.constats = blockingConstats(rep, 'ux');
-        l.next = codeReview(l); // la revue de code clôt toujours le cycle
         save(c);
+        // L'UX est la dernière étape (L221) : conforme, le lot conclut avec la revue de code ; sinon une correction (jamais une revue de code d'office), la revue de code et l'UX rejouée suivent.
+        if (summary.conforme)
+            await conclude(c, l.code, noCommitNote(l));
+        else
+            toFix(c, l.constats, 'UX non conforme');
         return;
     }
     l.code = summary;
@@ -1746,18 +1790,18 @@ async function reviewStep(c, kind) {
         l.ux = summary;
         l.uxVerdict = summary.verdict;
     }
-    const uxOk = l.small || !l.ux || l.ux.conforme;
     const minors = minorConstats(rep);
     // Revue conforme avec mineurs : une seule passe de correction des mineurs, avant de conclure (rien sous le tapis).
-    // Budget épuisé : la passe n'aurait aucune session pour la jouer, le lot conclut sur la revue conforme et rend les mineurs.
-    const wanted = summary.conforme && uxOk && !l.minorPass && !l.light && minors.length > 0; // lot léger : les mineurs restent des notes (L108)
+    // Budget épuisé : la passe n'aurait aucune session pour la jouer, les mineurs sont rendus en propositions ; la revue conforme conclut le lot,
+    // sauf un lot visible avec orchestrate.ux, qui passe à next = 'ux' puis reste suspendu tant que le budget de la vague l'est.
+    const wanted = summary.conforme && !l.minorPass && !l.light && minors.length > 0; // lot léger : les mineurs restent des notes (L108)
     const noBudget = wanted && (w.budget.exhausted || !fixAffordable(l)) && !w.incident && !w.quota.hit;
     const minorPass = wanted && !noBudget;
     if (noBudget)
         l.warnings.push(`${w.budget.exhausted ? 'budget atteint' : 'budget du lot trop juste pour payer la correction et la revue courte qui la suivrait'} : la passe des mineurs n'a pas eu lieu, mineurs rendus en propositions`);
     // Les mineurs confiés à la passe ont pu être proposés par une revue non conforme antérieure : si la revue qui la suit est
     // conforme, ils sont traités et ne restent pas en propositions (ceux que cette revue signale encore sont ajoutés juste après).
-    if (l.minorPass && !minorPass && summary.conforme && uxOk && l.minorLines?.length) {
+    if (l.minorPass && !minorPass && summary.conforme && l.minorLines?.length) {
         // Chaque mineur confié retire UNE proposition : la même ligne d'abord, sinon une de même fichier et même texte (le correctif a pu décaler la ligne).
         // Un autre mineur de même fichier et même texte, à une autre ligne, reste donc proposé. Limite connue : un texte reformulé n'est pas reconnu et reste proposé.
         const left = [...l.proposals];
@@ -1774,7 +1818,7 @@ async function reviewStep(c, kind) {
         l.minorLines = [];
     }
     addProposals(c, rep, 'code', !minorPass);
-    if (summary.conforme && uxOk)
+    if (summary.conforme)
         (l.reviewCounts ??= []).push(0); // une revue conforme compte pour 0 dans la comparaison de la convergence (L205)
     if (minorPass) {
         l.minorPass = true;
@@ -1786,18 +1830,19 @@ async function reviewStep(c, kind) {
         save(c);
         return;
     }
-    if (summary.conforme && uxOk) {
-        await conclude(c, summary);
+    if (summary.conforme) {
+        if (uxAfterReview(c)) {
+            l.next = 'ux';
+            save(c);
+        }
+        else
+            await conclude(c, summary);
         return;
     }
-    const constats = [...blockingConstats(rep, 'code'), ...(!l.small && l.ux && !l.ux.conforme ? uxConstatsKept(c) : [])];
+    const constats = blockingConstats(rep, 'code');
     (l.reviewCounts ??= []).push(constats.length);
     toFix(c, constats, 'revue non conforme');
 }
-/** Constats UX de la dernière revue UX, gardés dans l'état par la revue elle-même (l.constats avant la revue de code). */
-function uxConstatsKept(c) {
-    return c.lot.constats.filter((k) => k.source === 'ux');
-}
 /** Revue conforme : le verdict est enregistré avec le sha relu, puis le commit du plan. `raf done` reste au lead. */
 async function conclude(c, code, minorNote = '') {
     const l = c.lot;

package/dist/orchestrate/fiche.js

@@ -13,10 +13,10 @@ export function ficheReviewText(o) {
         lines.push('', 'Points of the first review that the spec writer had to fix:', ...bulletLines(o.previous));
     return lines.join('\n');
 }
-/** Consigne de la seconde passe `spec` : les constats bloquants et majeurs des revues de la fiche (et de la maquette d'un lot mixte), ensemble. */
-export function reviewedSheetText(constats, mockup) {
+/** Consigne de la passe `spec` qui suit une revue : les constats bloquants et majeurs des revues de la fiche (et de la maquette d'un lot mixte), ensemble, la session `run` sur `max`. */
+export function reviewedSheetText(constats, mockup, o) {
     return [
-        `The review of your ${mockup ? 'sheet and mockup' : 'sheet'} found the blocking and major points below. Fix exactly these in the sheet${mockup ? ', the mockup and the captures' : ''} (one more pass only: it is reviewed again, and what remains goes back to the lead). Keep the sheet consistent: every rule sourced or a hypothesis with its \`si_faux\`, every rule attached to a case and tested, every contract with its errors:`,
+        `The review of your ${mockup ? 'sheet and mockup' : 'sheet'} found the blocking and major points below. Fix exactly these in the sheet${mockup ? ', the mockup and the captures' : ''} (spec session ${o.run} of ${o.max}: it is reviewed again, and what remains once the sessions are used goes back to the lead). Keep the sheet consistent: every rule sourced or a hypothesis with its \`si_faux\`, every rule attached to a case and tested, every contract with its errors:`,
         ...bulletLines(constats),
     ].join('\n');
 }

package/dist/orchestrate/maquette.js

@@ -1,27 +1,28 @@
 import { posix } from 'node:path';
 import { LARGEURS } from '../spec.js';
-// Revue UX de la maquette (L172, spec etape-spec S4) : ce que le programme dit à l'agent ux-reviewer en mode « maquette », et à l'agent spec à la seconde passe.
+// Revue UX de la maquette (L172, spec etape-spec S4) : ce que le programme dit à l'agent ux-reviewer en mode « maquette », et à l'agent spec à la passe suivante.
 /** Une ligne par constat : gravité, endroit, texte. */
 export const bulletLines = (constats) => constats.map((k) => `- [${k.gravite}] ${k.fichier ? `${k.fichier}${k.ligne ? `:${k.ligne}` : ''} — ` : ''}${k.texte}`);
-/** Consigne de la revue de maquette dans le brief : la fiche, la maquette, les captures attendues, la passe en cours. */
+/** Consigne de la revue de maquette dans le brief : la fiche, la maquette, les captures attendues, le rang de la revue sur le plafond `max` (L230). */
 export function maquetteText(o) {
     const folder = posix.dirname(o.fiche);
-    const second = o.passes >= 1;
+    const rank = o.passes + 1;
+    const later = rank >= 2;
     const lines = [
         `Mockup mode: review the mockup \`${folder}/maquette.html\` against its sheet \`${o.fiche}\`. It is a local file, not an application: open it directly (file URL), do not start any server.`,
         `The spec writer committed the captures \`${folder}/maquette-<état>-<largeur>.png\` (one per state of the sheet and per width: ${LARGEURS.join(' and ')} px): look at every one, and re-capture a state yourself when a capture looks stale. Each state is the section \`#etat-<état>\` of the mockup.`,
-        second
-            ? 'This is the second and last review: the spec writer fixed the points of the first one (below). Check them first, then review the whole mockup again.'
-            : 'This is the first review of this mockup.',
+        later
+            ? `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 (second && o.previous?.length)
-        lines.push('', 'Points of the first review that the spec writer had to fix:', ...bulletLines(o.previous));
+    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');
 }
-/** Consigne de la seconde passe `spec` : les constats bloquants et majeurs de la revue UX de la maquette. */
-export function reviewedText(constats) {
+/** Consigne de la passe `spec` qui suit une revue : les constats bloquants et majeurs de la revue UX de la maquette, la session `run` sur `max`. */
+export function reviewedText(constats, o) {
     return [
-        'The UX review of your mockup found the blocking and major points below. Fix exactly these in the mockup, the captures and the sheet (one more pass only: the mockup is reviewed again, and what remains goes back to the lead). Keep the sheet consistent with the mockup — every field, every rule message visible in the state its `etat` names, every `data-testid`:',
+        `The UX review of your mockup found the blocking and major points below. Fix exactly these in the mockup, the captures and the sheet (spec session ${o.run} of ${o.max}: the mockup is reviewed again, and what remains after the last review goes back to the lead). Keep the sheet consistent with the mockup — every field, every rule message visible in the state its \`etat\` names, every \`data-testid\`:`,
         ...bulletLines(constats),
     ].join('\n');
 }

package/dist/orchestrate/schemas.js

@@ -40,7 +40,7 @@ export const REVIEW_SCHEMA = {
         bloquants: num,
         majeurs: num,
         mineurs: num,
-        constats: { type: 'array', items: { type: 'object', properties: { gravite: { type: 'string', enum: ['bloquant', 'majeur', 'mineur'] }, fichier: str, ligne: num, texte: str }, required: ['gravite', 'texte'] } },
+        constats: { type: 'array', items: { type: 'object', properties: { gravite: { type: 'string', enum: ['bloquant', 'majeur', 'mineur'] }, fichier: str, ligne: num, texte: str, inchange: { type: 'boolean', description: 'optional, review 2 or later of a mockup: true when the finding is on a point the spec writer did not change and the previous review had not raised' } }, required: ['gravite', 'texte'] } },
         sousTaches: strings,
         nonVerifie: strings,
         verdict: str,

package/dist/orchestrate/snapshot.js

@@ -89,6 +89,20 @@ export function waveReadsControl(waveDir) {
         return false;
     }
 }
+/**
+ * L'instantané de la vague connaît-il `--budget projet:lot=+N` (L223) ? Un instantané plus ancien relit l'argument avec son `parseBudget` et le refuse
+ * comme budget invalide. Sans instantané : rien à relire, on suppose que oui.
+ */
+export function waveReadsLotBudget(waveDir) {
+    if (!snapshotExists(waveDir))
+        return true;
+    try {
+        return readFileSync(join(toolDirOf(waveDir), 'dist', 'orchestrate', 'command.js'), 'utf8').includes('lotBudgets');
+    }
+    catch {
+        return false;
+    }
+}
 /** Relance réelle : un processus node sur la copie, signaux transmis, code de sortie rendu. */
 export function spawnReexec(toolDir, argv, env, sink) {
     return new Promise((resolve, reject) => {

package/dist/plan.js

@@ -3,9 +3,10 @@ import { dirname } from 'node:path';
 import { isMap, isSeq, parseDocument } from 'yaml';
 import { isDay, toDay } from './dates.js';
 export const STATUSES = ['todo', 'doing', 'done', 'dropped'];
+export const GATE_INVALID = 'gate invalide : count: entier ≥ 1 et un critère spec: true ou screen: page attendus';
 export class RafError extends Error {
 }
-export const FIELDS = ['id', 'title', 'status', 'estimate', 'quickwin', 'visible', 'screen', 'spec', 'public', 'every', 'last', 'after', 'created', 'started', 'finished', 'notes', 'repos', 'parent'];
+export const FIELDS = ['id', 'title', 'status', 'estimate', 'quickwin', 'visible', 'screen', 'spec', 'public', 'every', 'last', 'after', 'created', 'started', 'finished', 'notes', 'repos', 'parent', 'gate'];
 /** Nature de l'écran d'un lot visible : nouvelle page, nouveau composant, parcours modifié. */
 export const SCREENS = ['page', 'component', 'journey'];
 export function isOpen(status) {
@@ -398,6 +399,28 @@ export class Plan {
         if (status === 'done' || status === 'dropped')
             node.set('finished', today);
     }
+    /**
+     * Remet en attente un lot démarré (doing → todo, `started` retiré, note datée) — `raf todo` (L220). Les refus passent dans
+     * l'ordre : plan modifiable, lot et non sous-tâche, lot connu, lot doing ; `commits` n'est lu qu'ensuite (il lit git) et un lot
+     * qui a du travail est refusé. Les sous-tâches et les autres clés du lot ne bougent pas.
+     */
+    putBack(ref, today, reason, commits) {
+        this.writable();
+        if (ref.includes('/'))
+            throw new RafError(`raf todo se pose sur un lot, pas une sous-tâche : ${ref}`);
+        const lot = this.lot(ref);
+        if (lot.status === 'todo')
+            throw new RafError(`${ref} est déjà todo`);
+        if (lot.status !== 'doing')
+            throw new RafError(`${ref} est ${lot.status} ; le rouvrir à la main dans le YAML si c'est voulu`);
+        const n = commits();
+        if (n > 0)
+            throw new RafError(`${ref} a ${n} commit(s) qui le citent : le remettre en attente perdrait leur lien — raf drop ou le laisser doing`);
+        const node = this.lotNode(ref);
+        node.set('status', 'todo');
+        node.delete('started');
+        this.note(ref, reason.trim() ? `remis en attente : ${reason.trim()}` : 'remis en attente', today);
+    }
     /** Pose, remplace (texte) ou efface (null) le titre public d'un lot ; la clé suit `title`. */
     setPublic(ref, text) {
         this.writable();
@@ -541,6 +564,7 @@ function foreignLots(raw, format) {
             finished: day('finished'),
             notes: typeof notes === 'string' ? [{ text: notes }] : notes,
             repos: pick('repos'),
+            gate: pick('gate'),
         }, problems);
         const parent = pick('parent');
         return { lot, parent: parent == null ? undefined : String(parent) };
@@ -559,6 +583,25 @@ function foreignLots(raw, format) {
     }
     return lots;
 }
+/** 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] };
+}
 /** Un titre public vide ne dirait rien au public : refusé plutôt qu'écrit. */
 function cleanPublic(text) {
     const t = text.trim();
@@ -595,6 +638,7 @@ function normalizeLot(raw, problems = []) {
         else if (raw.spec !== false)
             problems.push(`spec : true ou false attendu (reçu « ${String(raw.spec)} »)`);
     }
+    const gate = readGate(raw.gate, problems);
     return {
         id: String(raw.id),
         title: String(raw.title ?? ''),
@@ -604,6 +648,7 @@ function normalizeLot(raw, problems = []) {
         visible: raw.visible === true,
         ...(screen ? { screen } : {}),
         ...(spec ? { spec } : {}),
+        ...(gate ? { gate } : {}),
         ...(typeof raw.public === 'string' && raw.public.trim() !== '' ? { public: raw.public.trim() } : {}),
         ...(Number.isInteger(raw.every) && raw.every > 0 ? { every: raw.every } : {}),
         ...(last ? { last } : {}),

package/dist/session.js

@@ -1,7 +1,7 @@
 import { spawnSync } from 'node:child_process';
 import { CLEAN_DAYS, scanStale } from './clean.js';
 import { dueLine, isRecurring, recurringByDue } from './recurring.js';
-import { audit, exemptPlanOnly, nextUp, planCommits } from './audit.js';
+import { audit, exemptPlanOnly, gateWaiting, nextUp, planCommits } from './audit.js';
 import { diffDays, maxDay } from './dates.js';
 import { repoStatus } from './git.js';
 import { linkCommits } from './link.js';
@@ -109,7 +109,7 @@ export function sessionStart(ctx, opts) {
     const lock = lockStatus(ctx.shared);
     if (lock)
         out(`\n${lock.line}`);
-    const { doing, ready } = nextUp(lots);
+    const { doing, ready, blocked } = nextUp(lots);
     out('\nEn cours');
     if (doing.length === 0)
         out('  (rien)');
@@ -119,6 +119,7 @@ export function sessionStart(ctx, opts) {
         const state = last ? `dernière activité ${last}${idle > opts.idle ? `, silencieux depuis ${idle} j` : ''}` : 'aucune activité';
         out(`  ${l.id}  ${l.title}  (${state})`);
     }
+    section(out, 'En attente', gateWaiting(lots, blocked).map(({ lot, text }) => `${lot.id}  ${lot.title}  (${text})`));
     const recent = period(ctx, opts.since);
     const done = byLotLines(recent);
     if (recent.orphans.length)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sylad/cadence",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "A small, repo-native working method: a versioned plan linked to your commits, a changelog with screenshots, session rituals and deliveries proven by their effect.",
   "license": "MIT",
   "author": "Sylvain Ladoire",

package/skills/lead/SKILL.md

@@ -90,12 +90,11 @@ ends `interrupted`, and `--resume` takes it up again. To take a lot out of a wav
 `--resume --drop <project>:<lot>` (the lot is handed back instead of being replayed). Neither kills a session.
 
 `cadence orchestrate --dry-run …` first when a precondition is in doubt. The program, not the lead, runs
-for each lot a fresh short session per step — implementation (Sonnet), UX review if the lot is `visible`
-and the project declares how to see its app (`orchestrate.ux` in `cadence.yaml`), code review last
+for each lot a fresh short session per step — implementation (Sonnet), code review
 (Opus, the `code-reviewer` agent; Sonnet, with no pass on the minor findings, for a lot whose estimate is
 ≤ 0.25 d — `orchestrate.review` in `cadence.yaml`; a blocker or major finding still brings a correction and an
 Opus review), a correction in a new session if the review is not compliant (two
-passes at most, a third when the review converges: blocking + major findings down from one review to the next and only one left) — and records `raf review` itself when the code review is compliant. A lot with `spec: true` (no screen) goes `spec → fiche → accept` before the code: the `code-reviewer` reviews its back-end sheet, and the hypotheses of the final sheet come back in the table as « hypothèse de la fiche » lines, which the lead relays to the human. The state is in
+passes at most, a third when the review converges: blocking + major findings down from one review to the next and only one left), then, once, a UX review if the lot is `visible` and the project declares how to see its app (`orchestrate.ux` in `cadence.yaml`) — and records `raf review` itself when the code review is compliant and the UX review too. A lot with `spec: true` (no screen) goes `spec → fiche → accept` before the code: the `code-reviewer` reviews its back-end sheet, and the hypotheses of the final sheet come back in the table as « hypothèse de la fiche » lines, which the lead relays to the human. The state is in
 `.cadence/runs/<wave>/`, not in this conversation. `@haiku` only when the human writes it, for a
 mechanical lot. Exit code: 0 all ready · 1 some lots handed back · 2 refused before acting · 3 wave
 suspended (budget or usage limit; `--resume --budget …` continues).

package/templates/orchestrate/accept-back.md

@@ -5,6 +5,7 @@ Acceptance tests of the behaviour of lot `{{lot}}` in `{{chemin}}`, as the accep
 Rules:
 - One or more cases per rule of the sheet, named exactly as the sheet plans it (`regles[].tests`, e.g. `R5 — une entrée de 14 jours est refusée : null`); the tests call the contracts of `contrats[]` as close as possible (the controller or the service for an HTTP call, the method of the job for a `job`), and simulate the external sources from `entree`. What cannot be automated is out of scope.
 - Every test must FAIL for now, because the feature is missing (not because of a typo or a broken setup): the program runs the dedicated command and refuses tests that pass.
+- Cite what you assert: above each assertion, a comment cites the rule and the sentence of its statement that it verifies (`// R4 — « <sentence of the rule> »`), and you assert nothing beyond that sentence (a rule that forbids X does not license asserting that Y never happens). Self-check before the commit, assertion by assertion: one with no sentence of the sheet behind it is removed, or listed under "choix" of your report; a test that asserts more than its rule says binds the implementer to a requirement nobody wrote.
 - Do not touch the sheet, the plan or any application code. Do not push, deliver, run `raf done`, `raf ux` or `raf review`.
 - Commit with explicit paths (never `git add -A` or `commit -a`), ONE commit citing the lot (`test({{lot}}): acceptation R1–Rn (rouge)`) with the test files, the acceptation file and the runner configuration, and leave the working tree clean. The program seals the acceptation file afterwards (it adds the fingerprint of each test file): never write `empreintes` or `vert: true` yourself.
 Never run `git checkout` or `git switch` to another commit or branch in this repository: the orchestrator watches it and a moved HEAD breaks the other sessions of the wave. To look at another sha, use a throwaway `git worktree add --detach <tmp> <sha>`, removed afterwards.

package/templates/orchestrate/accept.md

@@ -5,6 +5,7 @@ Acceptance tests of the screen of lot `{{lot}}` in `{{chemin}}`, as the acceptan
 Rules:
 - One or more cases per rule of the sheet, named exactly as the sheet plans it (`regles[].tests`, e.g. `R3 — erreur : message et bouton Réessayer`); selectors are the `data-testid` of the fields (= field ids of the sheet); API calls are simulated from `actions[]`. What cannot be automated (rendering, ergonomics, readability) is out of scope.
 - Every test must FAIL for now, because the feature is missing (not because of a typo or a broken setup): the program runs the dedicated command and refuses tests that pass.
+- Cite what you assert: above each assertion, a comment cites the rule and the sentence of its statement that it verifies (`// R4 — « <sentence of the rule> »`), and you assert nothing beyond that sentence (a rule that forbids X does not license asserting that Y never happens). Self-check before the commit, assertion by assertion: one with no sentence of the sheet behind it is removed, or listed under "choix" of your report; a test that asserts more than its rule says binds the implementer to a requirement nobody wrote.
 - Do not touch the sheet, the mockup, the plan or any application code. Do not push, deliver, run `raf done`, `raf ux` or `raf review`.
 - Commit with explicit paths (never `git add -A` or `commit -a`), ONE commit citing the lot (`test({{lot}}): acceptation R1–Rn (rouge)`) with the test files, the acceptation file and the runner configuration, and leave the working tree clean. The program seals the acceptation file afterwards (it adds the fingerprint of each test file): never write `empreintes` or `vert: true` yourself.
 Never run `git checkout` or `git switch` to another commit or branch in this repository: the orchestrator watches it and a moved HEAD breaks the other sessions of the wave. To look at another sha, use a throwaway `git worktree add --detach <tmp> <sha>`, removed afterwards.

package/templates/orchestrate/fix.md

@@ -12,7 +12,16 @@ Rules: test first; commit each fix as soon as its tests pass, with explicit path
 `git add -A` or `commit -a`), and a message that cites the lot (`fix({{lot}}): …`); run the project's
 full test suite and build before reporting; do not push, deliver, run `raf done`, `raf ux` or
 `raf review`. Read the project's CLAUDE.md first.
+Sealed test of ANOTHER lot: if what your own sealed tests require contradicts a sealed acceptance test of another lot (an `acceptation-<lot>.json` that is not yours), it is a question to the lead naming both tests (file and `Rn — …` name of each): never modify, rewrite or reseal it and never pick a side. Stop there and put the question in your report. The program compares the fingerprints of the sealed tests of every other lot at the end of each session and hands your lot back, naming the first offending commit, before any review.
 Never run `git checkout` or `git switch` to another commit or branch in this repository: the orchestrator watches it and a moved HEAD breaks the other sessions of the wave. To look at another sha, use a throwaway `git worktree add --detach <tmp> <sha>`, removed afterwards.
+Self-check before handing back (the recurring findings of the reviews), covering only what you changed: go through this list point by point on your own fix commits before you report, and touch nothing else:
+- documentation: the README and the architecture documentation describe the behaviour, updated in the same commits as the behaviour (and the CHANGELOG);
+- tests: one test per rule of the fiche, named « Rn — … »; with no fiche, one test per business rule of the lot, named after it;
+- no dead code, and no test that cannot fail: a test whose assertion is always true, or that does not exercise the rule it names;
+- screens: for a modified screen, the capture due of each state, at 1440 and 390 px, with a relative file name; a lot with no modified screen owes none, and says so;
+- no false comment: a comment, a docstring or a message never describes a behaviour the code no longer has or does not have.
+A point you cannot hold is written under "choix" or "nonVerifie" of your report, not left unsaid.
+
 If a finding is wrong, say so under "choix" with the reason. Ask (under "questions") only when a fix needs a decision that passes the rule below.
 A question is legitimate only if it names what it would change: the scope of the lot, the architecture, or a costly rollback (data, production, public API);
 otherwise it is a choice: decide, write the alternative you did not take, go on. Minor choices to settle yourself:

package/templates/orchestrate/implement.md

@@ -7,8 +7,17 @@ Rules: test first; commit each sub-part as soon as its tests pass, with explicit
 `git add -A` or `commit -a`), and a message that cites the lot (`feat({{lot}}): …`); run the project's
 full test suite and build before reporting; do not push, deliver, run `raf done`, `raf ux` or
 `raf review`.
+Sealed test of ANOTHER lot: if what your own sealed tests require contradicts a sealed acceptance test of another lot (an `acceptation-<lot>.json` that is not yours), it is a question to the lead naming both tests (file and `Rn — …` name of each): never modify, rewrite or reseal it and never pick a side. Stop there and put the question in your report. The program compares the fingerprints of the sealed tests of every other lot at the end of each session and hands your lot back, naming the first offending commit, before any review.
 Never run `git checkout` or `git switch` to another commit or branch in this repository: the orchestrator watches it and a moved HEAD breaks the other sessions of the wave. To look at another sha, use a throwaway `git worktree add --detach <tmp> <sha>`, removed afterwards.
 Documentation: the project's README (and its usage documentation) describes the behaviour you deliver, updated in the same commits, like the CHANGELOG — a README that does not follow your change is a major finding of the review.
+Self-check before handing back (the recurring findings of the reviews). Go through this list point by point on your own commits before you report, and fix what is missing:
+- documentation: the README and the architecture documentation describe the behaviour, updated in the same commits as the behaviour (and the CHANGELOG);
+- tests: one test per rule of the fiche, named « Rn — … »; with no fiche, one test per business rule of the lot, named after it;
+- no dead code, and no test that cannot fail: a test whose assertion is always true, or that does not exercise the rule it names;
+- screens: for a modified screen, the capture due of each state, at 1440 and 390 px, with a relative file name; a lot with no modified screen owes none, and says so;
+- no false comment: a comment, a docstring or a message never describes a behaviour the code no longer has or does not have.
+A point you cannot hold is written under "choix" or "nonVerifie" of your report, not left unsaid.
+
 Decide minor interpretation questions yourself (the wording of a message, a name, a default, the
 reading of an ambiguous line of the lot) and list each one under "choix" in your report, with the
 alternative you did not take — the reviewer re-reads them. Stop and ask (under "questions") only on a real blocker.