@sylad/cadence 1.1.0 → 1.2.0

package/dist/orchestrate/aval.js

@@ -1,30 +1,46 @@
 import { posix } from 'node:path';
 import { LARGEURS } from '../spec.js';
 const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
-/** Une ligne par règle de la fiche : id, [état, statut], énoncé, message exact, tests prévus. Vide quand le document n'est pas une fiche. */
+/** Une ligne par règle de la fiche : id, [état ou cas, statut], énoncé, message exact, tests prévus. Vide quand le document n'est pas une fiche. */
 export function ficheRules(doc) {
     if (!isObj(doc) || !Array.isArray(doc.regles))
         return [];
     return doc.regles.filter(isObj).map((r) => {
         const message = typeof r.message === 'string' ? ` Message: « ${r.message} ».` : '';
         const tests = Array.isArray(r.tests) ? ` Tests: ${r.tests.map((t) => `« ${String(t)} »`).join(', ')}.` : '';
-        return `- ${String(r.id)} [${String(r.etat)}, ${String(r.statut)}] ${String(r.enonce ?? '').trim()}${message}${tests}`;
+        const where = typeof r.etat === 'string' ? r.etat : Array.isArray(r.cas) ? r.cas.join(', ') : '';
+        return `- ${String(r.id)} [${where ? `${where}, ` : ''}${String(r.statut)}] ${String(r.enonce ?? '').trim()}${message}${tests}`;
     });
 }
+/** Une ligne par contrat de la fiche back : id, appel, entrée, sortie, erreurs (code et message exact). Vide sans contrats. */
+export function ficheContracts(doc) {
+    if (!isObj(doc) || !Array.isArray(doc.contrats))
+        return [];
+    return doc.contrats.filter(isObj).map((c) => {
+        const erreurs = Array.isArray(c.erreurs) && c.erreurs.length ? ` Errors: ${c.erreurs.filter(isObj).map((e) => `${String(e.code)} « ${String(e.message)} »`).join(', ')}.` : '';
+        return `- ${String(c.id)} ${String(c.appel)} — input: ${String(c.entree ?? '').trim()}; output: ${String(c.sortie ?? '').trim()}.${erreurs}`;
+    });
+}
+/** Le document a-t-il une partie écran (`ecran`) ? Une fiche back seule n'en a pas : ni maquette, ni captures. */
+export const hasScreenPart = (doc) => isObj(doc) && isObj(doc.ecran);
 /** Consigne de la fiche pour une étape en aval : `{{fiche}}` des gabarits implement, fix, review et ux. */
 export function avalFicheText(kind, o) {
     const folder = posix.dirname(o.fiche);
     const maquette = `${folder}/maquette.html`;
-    const head = `This lot has a screen sheet: \`${o.fiche}\` (mockup \`${maquette}\`). It is the reference of the screen; its rules are:\n${o.rules.join('\n')}`;
+    const screen = o.screen !== false;
+    const contracts = o.contracts?.length ? `\nIts contracts (the calls the code must hold, with the exact codes and messages of their errors) are:\n${o.contracts.join('\n')}` : '';
+    const head = screen
+        ? `This lot has a screen sheet: \`${o.fiche}\` (mockup \`${maquette}\`). It is the reference of the screen; its rules are:\n${o.rules.join('\n')}${contracts}`
+        : `This lot has a spec sheet: \`${o.fiche}\` (no screen: use cases, rules, contracts and data). It is the reference of the behaviour; its rules are:\n${o.rules.join('\n')}${contracts}`;
     if (kind === 'implement' || kind === 'fix') {
         return [
             head,
-            kind === 'implement' ? 'Read the sheet and the mockup before the first test.' : 'The sheet stays the reference of the fix: a finding that contradicts it is contested under "choix" with the rule.',
+            kind === 'implement' ? `Read the sheet${screen ? ' and the mockup' : ''} before the first test.` : 'The sheet stays the reference of the fix: a finding that contradicts it is contested under "choix" with the rule.',
             o.acceptation
                 ? `The acceptance tests are already written and committed red, from the sheet (files listed in \`${o.acceptation}\`): make them green without modifying them — the program compares them to the red commit, and a modified file hands the lot back. A change one of them needs is a question or a finding, never a silent edit.`
                 : '',
             'The tests you write yourself cite the rule they cover in their name (`R2 — …`); do not invent a rule: a case the sheet does not cover is noted in your report (under "nonVerifie" or "choix"), not coded.',
-            kind === 'implement' ? 'The News entry ends with a `## Hypothèses` section: one line per rule whose status is `hypothese` (`- R3 — what the screen does, and what changes if it is wrong`, taken from its `si_faux`); leave it out when the sheet has no hypothesis.' : '',
+            kind === 'implement' && screen ? 'The News entry ends with a `## Hypothèses` section: one line per rule whose status is `hypothese` (`- R3 — what the screen does, and what changes if it is wrong`, taken from its `si_faux`); leave it out when the sheet has no hypothesis.' : '',
         ]
             .filter(Boolean)
             .join('\n');
@@ -36,8 +52,11 @@ export function avalFicheText(kind, o) {
             o.acceptation
                 ? `The acceptance tests are listed in \`${o.acceptation}\`${o.rouge ? ` and were committed red at ${o.rouge.slice(0, 7)}` : ''}: each file must be unchanged since the red commit (\`git diff ${o.rouge ? o.rouge.slice(0, 7) : '<red commit>'} -- <file>\` is empty).`
                 : 'No acceptance tests were written for this lot: the tests of the rules are the ones the implementation wrote, named after the rule (`R2 — …`).',
+            o.contracts?.length ? 'Check each contract too: the code returns the output of the sheet and the exact codes and messages of its errors, and every datum the sheet announces without modification (`donnees`, `modification: aucune`) is intact. A contract that departs from the sheet is a major finding.' : '',
             'A rule without a test, an acceptance test modified since the red commit, a rule coded that is not in the sheet, and a test that is green without exercising its rule are major findings (name the rule and the file).',
-        ].join('\n');
+        ]
+            .filter(Boolean)
+            .join('\n');
     }
     return [
         `This lot has a screen sheet (\`${o.fiche}\`) and a mockup (\`${maquette}\`) that was already reviewed: this pass is a conformity pass, not the full audit. Compare the running app to the mockup, state by state (the states of the sheet), at ${LARGEURS.join(' and ')} px, against the captures \`${folder}/maquette-<état>-<largeur>.png\`.`,

package/dist/orchestrate/briefs.js

@@ -42,6 +42,9 @@ export function capturesText(captureDir) {
 const FILES = {
     precheck: 'precheck.md',
     spec: 'spec.md',
+    'spec-back': 'spec-back.md',
+    'accept-back': 'accept-back.md',
+    fiche: 'fiche.md',
     accept: 'accept.md',
     maquette: 'maquette.md',
     implement: 'implement.md',

package/dist/orchestrate/command.js

@@ -13,10 +13,11 @@ import { pidAlive, sharedStateDir } from '../state.js';
 import { acquireSlot, cadenceHome, freeSlots, liveSlots, liveWaves, registerWave, unregisterWave, updateWaveRepos } from './registry.js';
 import { loadTemplates, newsText, objective, renderBrief } from './briefs.js';
 import { acceptationFile, acceptText } from './accept.js';
+import { ficheReviewText } from './fiche.js';
 import { maquetteText } from './maquette.js';
 import { specText } from './spec.js';
 import { candidates, parsePriority, parseUntil, readPriority, stopReason } from './continue.js';
-import { Budget, DROPPED, MAX_PASSES, countInterrupted, handBackDroppedQuestions, needsPrecheck } from './cycle.js';
+import { Budget, DROPPED, MAX_PASSES, briefName, countInterrupted, handBackDroppedQuestions, needsPrecheck } from './cycle.js';
 import { canInstallPrePush, installPrePush, removePrePush, snapshot } from './guard.js';
 import { buildArgs, buildLocalArgs, killSessions, mcpServersFor, readAgents, realClaude } from './launch.js';
 import { activeLock, REPO_LOCK, releaseLock, takeLock } from './lock.js';
@@ -28,18 +29,45 @@ import { linkNodeBin, nvmVersionsDir, resolveNode } from './node-env.js';
 import { quotaText, renderTable } from './table.js';
 import { PACKAGE_ROOT, RESERVED_ENV, SnapshotRefusal, isSnapshotChild, resolveModulesDir, snapshotExists, waveReadsControl, withoutLaunchVars, spawnReexec, takeSnapshot, toolDirOf } from './snapshot.js';
 export const DEFAULT_BUDGET = 2_000_000;
-/** Tokens comptés par jour d'estimate (L78) ; mesuré le 06-10 : des lots de 0,5 j ont mangé 192 à 531 k, des lots de 1 j 455 à 468 k (2 M pour 6 lots). Depuis le plancher de L128 (450 k), ce plafond ne borne plus que les lots de plus de 1,125 j : les 5 lots du 06-10 passent tous. */
-const LOT_BUDGET_PER_DAY = 400_000;
 /**
- * Plancher (L128) : de quoi payer, dans le pire cas mesuré, une écriture, sa revue, une passe de correction et la revue
- * courte qui la suit (65 k, cf. REVIEW_RESERVE). Mesures de tous les `.cadence/runs/*` : passes fix médiane 45 k, p90 63 k,
- * max 112 k ; passes implement médiane 60 k, p90 93 k, max 282 k (L62). Pire cas : L62, 14 k de contrôle + 282 k d'écriture
- * + 80 k de revue = 376 k, plus 65 k de réserve = 441 k < 450 k, la passe fix part. Corrige L126 (200 k, rendu à la 2e passe) ;
- * L62 (estimate 1,5, donc 600 k) n'est pas changé par le plancher, la réserve de L145 couvre déjà sa correction et sa revue.
+ * Budget d'un lot ordinaire (L78, L128, recalibré L194). Mesuré sur le TOTAL de chaque lot dans `.cadence/runs` (toutes les vagues
+ * où il est passé, 250 lots, 11-10), rangé par estimate : jusqu'à 0,5 j p90 374 k (152 lots), de 0,5 à 1 j p90 732 k (88 lots, max
+ * 1,09 M), au-delà d'un jour p90 1,14 M pour les 10 lots de 1,25 à 2 j (570 k par jour d'estimate), max 1,7 M (L188). Le plafond
+ * de L78 (400 k par jour) rendait au lead, au deuxième tour, un lot de 1 j (L188 : 483 k puis 495 k).
  */
 const LOT_BUDGET_FLOOR = 450_000;
-/** Budget d'un lot, dérivé de son estimate : empêche quelques lots d'avaler le budget de la vague au détriment des autres. */
-export const lotBudget = (estimate) => Math.max(LOT_BUDGET_FLOOR, Math.round(estimate * LOT_BUDGET_PER_DAY));
+/** Lot de plus de 0,5 j et d'au plus 1 j : p90 mesuré du total, 732 k arrondis à 750 k. */
+const LOT_BUDGET_ONE_DAY = 750_000;
+/** Tokens par jour d'estimate au-delà d'un jour : p90 1,14 M pour 2 j. */
+const LOT_BUDGET_PER_DAY = 570_000;
+/**
+ * Total d'un lot à `screen:` (L194), étapes spec, maquette et accept comprises : p90 1,28 M sur 5 lots (L113 1,12 M, L25 1,28 M, L50 877 k,
+ * L85 758 k, L43 238 k), arrondi à 1,3 M. Remplace l'allocation de L191 (+350 k au budget d'estimate), qui ne payait ni l'UX de
+ * conformité ni les passes de correction.
+ */
+const SCREEN_LOT_BUDGET = 1_300_000;
+/**
+ * Allocation d'un lot à fiche `spec: true` (L188/L191), en plus du budget dérivé de l'estimate : sessions spec, fiche et accept hors de
+ * l'estimate d'écriture. Aucun lot `spec:` seul n'a encore été mesuré ; 350 k est le pire cas mesuré des étapes d'un lot à écran (ol L113 : 349 k).
+ */
+export const SPEC_STAGE_ALLOCATION = 350_000;
+/** Base mesurée d'un budget, pour `--dry-run` : l'estimate (et l'étape spec) d'où il sort. */
+export function lotBudgetBasis(estimate, stage) {
+    if (stage === 'screen' && lotBudget(estimate, stage) === SCREEN_LOT_BUDGET)
+        return "p90 mesuré du total d'un lot à écran, étapes spec, maquette et accept comprises";
+    const ordinary = lotBudget(estimate);
+    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`;
+}
+/** 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). */
+export const lotBudget = (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);
+};
 /** Sessions simultanées, toutes vagues confondues (`--max-sessions`, ou CADENCE_MAX_SESSIONS). */
 export const DEFAULT_MAX_SESSIONS = 2;
 /** `1500000`, `1.5M`, `800k`. */
@@ -58,11 +86,11 @@ export function parseMaxSessions(text, what = '--max-sessions') {
     return Number(text);
 }
 // une vague (2026-10-04-1412) n'a ni « : » ni « / » : leur présence désigne un lot, quel que soit son motif (R-M7/ux-1)
-const LOT_LIKE = /^(?:[\w.-]+:[\w.-][\w./-]*|[\w.-]+\/[\w./-]*|[A-Za-z]+\d+)(?:@\w+)?$/;
+const LOT_LIKE = /^(?:[\w.-]+(?:\/[\w.-]+)*:[\w.-][\w./-]*|[\w.-]+\/[\w./-]*|[A-Za-z]+\d+)(?:@\w+)?$/;
 const MODELS = ['sonnet', 'opus', 'haiku'];
 function lotArg(text) {
-    // le premier « : » sépare le projet du lot, un « @ » final le modèle ; le lot garde ses « / » (L120)
-    const m = /^(?:([\w.-]+):)?([\w.-][\w./-]*?)(?:@(\w+))?$/.exec(text);
+    // le premier « : » sépare le projet du lot, un « @ » final le modèle ; le lot garde ses « / » (L120), le projet peut être un chemin depuis le dossier (`groupe/gamma`, projet imbriqué de lead tour --depth, L201)
+    const m = /^(?:([\w.-]+(?:\/[\w.-]+)*):)?([\w.-][\w./-]*?)(?:@(\w+))?$/.exec(text);
     if (!m)
         throw new RafError(`lot invalide : ${text} (projet:lot, lot, projet:lot@haiku)`);
     if (m[3] && !MODELS.includes(m[3]))
@@ -243,11 +271,11 @@ async function preflight(args, targets, io, deps, launch, opts = {}) {
             continue;
         }
         const small = lot.estimate <= 0.5 || lot.quickwin;
-        const state = newLot({ project: t.project, repo: t.repo, lot: t.lot, title: lot.title, visible: lot.visible, small, ...(lot.screen ? { screen: lot.screen } : {}), model: t.model, readOnlyPlan: plan.readonly });
+        const state = newLot({ project: t.project, repo: t.repo, lot: t.lot, title: lot.title, visible: lot.visible, small, ...(lot.screen ? { screen: lot.screen } : {}), ...(lot.spec && !lot.screen ? { specLot: true } : {}), model: t.model, readOnlyPlan: plan.readonly });
         if (neighbours.repos.length)
             state.repos = neighbours.repos;
         state.light = lot.estimate <= env.config.review.threshold;
-        state.budget = lotBudget(lot.estimate);
+        state.budget = lotBudget(lot.estimate, lot.screen ? 'screen' : lot.spec ? 'spec' : undefined);
         state.dependsOn = lot.after.filter((d) => earlier.includes(d));
         if (node.kind === 'ok')
             state.node = { version: node.version, wanted: node.wanted, bin: node.bin, ...(node.skipped ? { skipped: node.skipped } : {}) };
@@ -284,7 +312,7 @@ function dryRun(lots, io, deps, budget, id) {
         const lot = env.loadPlan().lot(l.lot);
         const slot = repos.indexOf(l.repo);
         io.out(`${lotKey(l.project, l.lot)} — ${l.title}`);
-        io.out(`  budget du lot : ${l.budget} tokens comptés (dérivé de l'estimate)`);
+        io.out(`  budget du lot : ${l.budget} tokens comptés (base : ${lotBudgetBasis(lot.estimate, l.screen ? 'screen' : l.specLot ? 'spec' : undefined)})`);
         io.out(`  file ${basename(l.repo)} · ${slot < 2 ? `créneau ${slot + 1}` : 'en attente d\'un créneau'}`);
         if (l.repos?.length)
             io.out(`  dépôts voisins : ${l.repos.map((r) => r.rel).join(', ')} (verrou, garde de push et --add-dir ; leurs commits citent ${l.lot})`);
@@ -294,11 +322,14 @@ function dryRun(lots, io, deps, budget, id) {
             io.out(`  node : ${l.node.version} (.nvmrc ${l.node.wanted}${skipped})`);
         }
         const steps = [{ kind: 'implement', model: l.model }];
-        if (l.screen && env.config.accept)
+        const specStage = !!(l.screen || l.specLot);
+        if (specStage && env.config.accept)
             steps.unshift({ kind: 'accept', model: 'sonnet' });
         if (l.screen && env.config.maquette)
             steps.unshift({ kind: 'maquette', model: env.config.review.full });
-        if (l.screen)
+        if (l.specLot && env.config.fiche)
+            steps.unshift({ kind: 'fiche', model: 'sonnet' });
+        if (specStage)
             steps.unshift({ kind: 'spec', model: 'sonnet' });
         if (needsPrecheck(env.config, env.loadPlan(), l.repo, l.lot, l.repos))
             steps.unshift({ kind: 'precheck', model: env.config.precheckLocal ? 'local' : 'sonnet' });
@@ -316,24 +347,26 @@ function dryRun(lots, io, deps, budget, id) {
         const pwDir = join(resolve(RunStore.runsDir(io.cwd)), id, lotSlug(l.project, l.lot), 'playwright');
         // brief écrit par --dry-run = base d'une délégation à la main : aucun dossier de vague (il n'existe pas)
         const vars = { chemin: l.repo, lot: l.lot, titre: lot.title, objectif: objective(lot), commits: '', reponse: '', constats: '', ux: '', choix: '', checks: '', news: l.visible ? newsText(l.lot) : '', captures: '' };
-        if (l.screen)
-            vars.spec = specText({ dir: env.config.spec.dir, render: env.config.spec.render, screen: l.screen });
+        if (specStage)
+            vars.spec = specText({ dir: env.config.spec.dir, render: env.config.spec.render, screen: l.screen, back: !!l.specLot });
         if (l.screen && env.config.maquette)
             vars.maquette = maquetteText({ fiche: `${env.config.spec.dir}/<écran>/fiche.yaml`, passes: 0 });
-        if (l.screen && env.config.accept) {
-            const folder = `${env.config.spec.dir}/<écran>`;
-            vars.accept = acceptText({ fiche: `${folder}/fiche.yaml`, maquette: `${folder}/maquette.html`, acceptation: acceptationFile(`${folder}/fiche.yaml`, l.lot), command: env.config.accept, test: env.config.test });
+        if (l.specLot && env.config.fiche)
+            vars.fiche = ficheReviewText({ fiche: `${env.config.spec.dir}/<sujet>/fiche.yaml`, passes: 0 });
+        if (specStage && env.config.accept) {
+            const folder = `${env.config.spec.dir}/${l.screen ? '<écran>' : '<sujet>'}`;
+            vars.accept = acceptText({ fiche: `${folder}/fiche.yaml`, maquette: `${folder}/maquette.html`, screen: !!l.screen, back: false, acceptation: acceptationFile(`${folder}/fiche.yaml`, l.lot), command: env.config.accept ?? '', test: env.config.test });
         }
         for (const s of steps) {
             const file = join(tmp, `${lotSlug(l.project, l.lot)}--${s.kind}.md`);
-            const brief = renderBrief(s.kind, vars, deps.templatesDir);
+            const brief = renderBrief(briefName(l, s.kind), s.kind === 'fiche' || vars.fiche === undefined ? vars : { ...vars, fiche: '' }, deps.templatesDir); // la consigne de revue de fiche ne sert qu'au brief de la fiche : implement et review en sont la base d'une délégation à la main
             writeFileSync(file, brief);
-            const playwright = !!mcpServersFor(s.kind, l.visible, '', l.small).playwright;
+            const playwright = !!mcpServersFor(s.kind, l.visible, '', l.small, !!l.screen).playwright;
             const local = s.model === 'local';
             const args = (local ? buildLocalArgs : buildArgs)({ kind: s.kind, sessionId: '<uuid>', brief: '<brief>', model: s.model === 'local' ? 'sonnet' : s.model, local, effort: env.config.effort[s.kind === 'review-small' ? 'review' : s.kind], schema: schemaFor(s.kind), agent: s.kind === 'implement' ? undefined : s.kind === 'spec' ? 'spec-writer' : s.kind === 'accept' ? 'acceptance-writer' : s.kind === 'ux' || s.kind === 'maquette' ? 'ux-reviewer' : s.kind === 'precheck' ? 'precheck-reader' : 'code-reviewer', cwd: l.repo, wave: id, permissionMode: env.config.permissionMode, addDirs: [...env.config.addDirs, ...(playwright && (s.kind === 'implement' || s.kind === 'spec') ? [pwDir] : []), ...neighbourDirs(l)], timeoutMs: 0, mcpConfig: '<mcp>', playwright }, agents).map((a) => (a.startsWith('{') ? '<json>' : a));
             io.out(`  ${s.kind} : ${local ? 'claude-local' : 'claude'} ${args.join(' ')}`);
             io.out(`    brief : ${file}`);
-            const servers = Object.keys(mcpServersFor(s.kind, l.visible, '', l.small));
+            const servers = Object.keys(mcpServersFor(s.kind, l.visible, '', l.small, !!l.screen));
             io.out(`    mcp : ${servers.length ? `${servers.join(', ')} (captures dans le dossier de la vague : <vague>/${lotSlug(l.project, l.lot)}/playwright)` : 'aucun'}`);
         }
     }

package/dist/orchestrate/continue.js

@@ -72,7 +72,7 @@ export function candidates(launch, o) {
             continue;
         }
         for (const lot of ready) {
-            if (o.exclude.has(`${project}:${lot.id}`) || decisionPending(lot) || lotBudget(lot.estimate) > o.remaining)
+            if (o.exclude.has(`${project}:${lot.id}`) || decisionPending(lot) || lotBudget(lot.estimate, lot.screen ? 'screen' : lot.spec ? 'spec' : undefined) > o.remaining)
                 continue;
             out.push({ project, dir, lot });
         }