@sylad/cadence 0.28.0 → 1.1.0

package/dist/orchestrate/launch.js

@@ -4,17 +4,20 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from
 import { delimiter, join, resolve } from 'node:path';
 import { parse } from 'yaml';
 import { RafError } from '../plan.js';
+import { sandboxEnv } from './sandbox.js';
 import { killMarked, SESSION_MARK_VAR, TreeTracker } from '../proc.js';
 import { isQuotaMessage, lacksStructuredOutput, parseSession, salvageUsage, sumTokens, tokensOf } from './result.js';
 /**
- * Serveurs MCP d'une étape : Playwright pour `ux` et, sur un lot `visible`, pour `implement` et `fix` (fix-minors compris) ;
+ * Serveurs MCP d'une étape : Playwright pour `ux` et `maquette` (revue des captures et du HTML local, L172) et, sur un lot `visible`, pour `spec` (rendu 1440/390 de la maquette, L171), `implement` et `fix` (fix-minors compris) ;
  * et `review-small` d'un petit lot visible (sa seule revue d'ergonomie) ; rien pour `review`, ni pour un lot sans écran.
  * Sorties dans `outputDir`, hors du dépôt.
  */
 export function mcpServersFor(kind, visible, outputDir, small = false) {
-    if (!(kind === 'ux' || (visible && (kind === 'implement' || kind === 'fix' || (kind === 'review-small' && small)))))
+    if (!(kind === 'ux' || kind === 'maquette' || (visible && (kind === 'spec' || kind === 'implement' || kind === 'fix' || (kind === 'review-small' && small)))))
         return {};
-    return { playwright: { command: 'npx', args: ['-y', '@playwright/mcp@latest', '--output-dir', outputDir] } };
+    // La maquette est un fichier local : sans cette option le serveur bloque toute URL file:// (« Access to "file:" protocol is blocked »).
+    const files = kind === 'maquette' || kind === 'spec' ? ['--allow-unrestricted-file-access'] : [];
+    return { playwright: { command: 'npx', args: ['-y', '@playwright/mcp@latest', ...files, '--output-dir', outputDir] } };
 }
 /** Dossier de sortie du Playwright MCP d'un lot : `<lotDir>/playwright`, chemin absolu. */
 export function playwrightDir(lotDir) {
@@ -125,7 +128,8 @@ export function buildRetryArgs(spec, sessionId, agents) {
  * s'ajoutent à ceux de la session ; toujours rien après elle, c'est l'échec habituel.
  */
 export async function runSession(spec, deps) {
-    const launch = (args) => deps.claude(args, { local: spec.local, cwd: spec.cwd, env: { CADENCE_ORCHESTRATED: spec.wave, ...(spec.nodeBin || spec.toolBin ? { PATH: [spec.toolBin, spec.nodeBin, process.env.PATH ?? ''].filter(Boolean).join(delimiter) } : {}) }, timeoutMs: spec.timeoutMs, onSpawn: deps.onSpawn });
+    const sandbox = sandboxEnv(!!spec.prodAccess);
+    const launch = (args) => deps.claude(args, { local: spec.local, cwd: spec.cwd, unset: sandbox.unset, env: { CADENCE_ORCHESTRATED: spec.wave, ...sandbox.set, ...(spec.nodeBin || spec.toolBin ? { PATH: [spec.toolBin, spec.nodeBin, process.env.PATH ?? ''].filter(Boolean).join(delimiter) } : {}) }, timeoutMs: spec.timeoutMs, onSpawn: deps.onSpawn });
     const out = await launch(spec.local ? buildLocalArgs(spec, deps.agents) : buildArgs(spec, deps.agents));
     const first = classify(out);
     if (spec.local)
@@ -201,7 +205,10 @@ export function realClaude(bin, base = process.env, localBin = 'claude-local') {
         // `nohup srv &` échappe à tout relevé de l'arbre) : à la fin de la session, tout ce qui la porte est tué.
         const mark = randomUUID();
         marks.add(mark);
-        const child = spawn(opts.local ? localBin : bin, args, { cwd: opts.cwd, env: { ...base, ...opts.env, [SESSION_MARK_VAR]: mark }, stdio: ['ignore', 'pipe', 'pipe'], detached: true });
+        const inherited = { ...base };
+        for (const v of opts.unset ?? [])
+            delete inherited[v];
+        const child = spawn(opts.local ? localBin : bin, args, { cwd: opts.cwd, env: { ...inherited, ...opts.env, [SESSION_MARK_VAR]: mark }, stdio: ['ignore', 'pipe', 'pipe'], detached: true });
         const pid = child.pid;
         if (pid === undefined) {
             marks.delete(mark);

package/dist/orchestrate/maquette.js

@@ -0,0 +1,27 @@
+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.
+/** 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. */
+export function maquetteText(o) {
+    const folder = posix.dirname(o.fiche);
+    const second = o.passes >= 1;
+    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.',
+    ];
+    if (second && o.previous?.length)
+        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 de la revue UX de la maquette. */
+export function reviewedText(constats) {
+    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`:',
+        ...bulletLines(constats),
+    ].join('\n');
+}

package/dist/orchestrate/sandbox.js

@@ -0,0 +1,38 @@
+/**
+ * Bac à sable des sessions de vague (L168) : une session ne touche pas à la production. Idée reprise du sandbox de
+ * docker/docker-agent (réseau fermé par défaut), ramenée à ce que cadence maîtrise : l'environnement du processus.
+ *
+ * Mesuré sur Big-Blue : une session hérite de `KUBECONFIG` (qui désigne `~/.kube/config`, donc la prod) ; `kubectl` du
+ * PATH est un lien vers k3s, qui sans `KUBECONFIG` retombe sur `/etc/rancher/k3s/k3s.yaml`. `KUBECONFIG=/dev/null`
+ * coupe les deux : `kubectl get pods` répond « connection refused » sur localhost:8080.
+ *
+ * Limite : ce n'est pas une barrière. `~/.kube/config` reste lisible (même utilisateur) ; `kubectl --kubeconfig ~/.kube/config`
+ * ou `KUBECONFIG=~/.kube/config` rouvre le cluster. Le rendre illisible demande un bac à sable fichiers (hors de ce lot).
+ */
+/** Variables qui donnent un accès à la production ou au cloud : retirées de l'environnement des sessions. */
+export const PROD_VARS = [
+    'KUBERNETES_SERVICE_HOST',
+    'KUBERNETES_SERVICE_PORT',
+    'KUBE_TOKEN',
+    'ARGOCD_SERVER',
+    'ARGOCD_AUTH_TOKEN',
+    'ARGOCD_OPTS',
+    'CLOUDFLARE_API_TOKEN',
+    'CLOUDFLARE_API_KEY',
+    'CF_API_TOKEN',
+    'CF_API_KEY',
+    'AWS_ACCESS_KEY_ID',
+    'AWS_SECRET_ACCESS_KEY',
+    'AWS_SESSION_TOKEN',
+    'GOOGLE_APPLICATION_CREDENTIALS',
+    'AZURE_CLIENT_SECRET',
+    'GH_TOKEN',
+    'GITHUB_TOKEN',
+    'GH_ENTERPRISE_TOKEN',
+];
+/** Ce qu'il faut ajouter et retirer de l'environnement d'une session. `prodAccess` (cadence.yaml) lève la restriction. */
+export function sandboxEnv(prodAccess) {
+    if (prodAccess)
+        return { set: {}, unset: [] };
+    return { set: { KUBECONFIG: '/dev/null' }, unset: [...PROD_VARS] };
+}

package/dist/orchestrate/schemas.js

@@ -16,6 +16,21 @@ export const WORK_SCHEMA = {
     },
     required: ['commits', 'tests', 'build', 'nonVerifie', 'questions', 'resume'],
 };
+/**
+ * Sortie de l'étape spec : `sousSeuil` vaut une raison (une ligne) quand le lot ne change aucun écran, « » sinon ;
+ * `fiche` le chemin de la fiche écrite (relatif au dépôt), « » sous le seuil.
+ */
+export const SPEC_SCHEMA = {
+    type: 'object',
+    properties: { commits: WORK_SCHEMA.properties.commits, nonVerifie: strings, questions: strings, choix: strings, sousSeuil: str, fiche: { type: 'string', description: 'path of the sheet relative to the repository, or empty' }, resume: str },
+    required: ['commits', 'nonVerifie', 'questions', 'sousSeuil', 'fiche', 'resume'],
+};
+/** Sortie de l'étape accept : les tests d'acceptation rouges, commités avec leur acceptation.json. */
+export const ACCEPT_SCHEMA = {
+    type: 'object',
+    properties: { commits: WORK_SCHEMA.properties.commits, nonVerifie: strings, questions: strings, choix: strings, resume: str },
+    required: ['commits', 'nonVerifie', 'questions', 'resume'],
+};
 /** Sortie d'une revue (code, UX ou passe unique) : `verdict` est la ligne pour `raf review` / `raf ux`. */
 export const REVIEW_SCHEMA = {
     type: 'object',
@@ -36,7 +51,8 @@ export const PRECHECK_SCHEMA = {
     properties: { dejaPresent: { type: 'string', enum: ['oui', 'partiel', 'non'] }, preuves: strings, resume: str },
     required: ['dejaPresent', 'preuves', 'resume'],
 };
-export const schemaFor = (kind) => (kind === 'precheck' ? PRECHECK_SCHEMA : kind === 'implement' || kind === 'fix' ? WORK_SCHEMA : REVIEW_SCHEMA);
+/** Une revue de maquette rend le même rapport qu'une revue d'ergonomie (REVIEW_SCHEMA). */
+export const schemaFor = (kind) => (kind === 'precheck' ? PRECHECK_SCHEMA : kind === 'spec' ? SPEC_SCHEMA : kind === 'accept' ? ACCEPT_SCHEMA : kind === 'implement' || kind === 'fix' ? WORK_SCHEMA : REVIEW_SCHEMA);
 /** Contrôle la forme d'une sortie structurée : un champ absent ou mal typé est une erreur nommée. */
 export function checkShape(value, schema) {
     if (!value || typeof value !== 'object' || Array.isArray(value))

package/dist/orchestrate/spec.js

@@ -0,0 +1,140 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse } from 'yaml';
+import { checkFiche, fichesDuDossier, LARGEURS } from '../spec.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>/fiche.yaml`, ou null : sert à ne pas rejouer une spec déjà écrite. */
+export function findFiche(repo, dir, lot) {
+    const hit = fichesDuDossier(repo, dir).find(({ doc }) => isObj(doc.ecran) && doc.ecran.lot === lot);
+    return hit ? `${dir}/${hit.name}/fiche.yaml` : null;
+}
+/** Texte sans accents ni majuscules, pour les mots-clés. */
+const plain = (s) => s.normalize('NFD').replace(/[̀-ͯ]/g, '').toLowerCase();
+/**
+ * Les quatre catégories de choix coûteux à défaire (spec etape-spec § 4), en mots-clés : modèle ou stockage de données,
+ * contrat d'API ou route publiée, action destructive ou irréversible, règle qui en contredit une autre.
+ * Garde-fou du programme : le jugement reste à l'agent, qui doit déjà avoir posé la question.
+ */
+const COSTLY = [
+    ['modèle ou stockage de données', /modele de donnees|schema de donnees|stockage|migration|base de donnees|donnees? (utilisateur|creees?)/],
+    ["contrat d'API ou route publiée", /contrat d'?api|api (publique?|partagee?)|endpoint (public|partage)|(route|url) (deja )?publiee?/],
+    ['action destructive ou irréversible', /supprim|suppression|irreversible|destructi|paiement|(envoi|envoie)\b/],
+    ['règle sourcée contredite', /contredit|contradiction/],
+];
+/** Un mot de négation, ses articles éventuels et le mot qu'il nie (« rien d'irréversible », « sans suppression », « pas de paiement »). */
+const NEGATED = /\b(?:rien|aucune?|pas|sans|jamais)\s+(?:(?:d'|l'|de |du |des |d'un |d'une |un |une |le |la |les )\s*)*[\p{L}-]+/gu;
+/** Règles `hypothese` dont `si_faux` relève d'un choix coûteux à défaire : une question, pas une hypothèse. */
+export function costlyHypotheses(doc) {
+    if (!isObj(doc))
+        return [];
+    const out = [];
+    for (const r of list(doc.regles)) {
+        if (r.statut !== 'hypothese' || typeof r.si_faux !== 'string')
+            continue;
+        const text = plain(r.si_faux).replace(/[’‘]/g, "'").replace(NEGATED, ' ');
+        const hit = COSTLY.find(([, re]) => re.test(text));
+        if (hit)
+            out.push({ id: String(r.id), categorie: hit[0], siFaux: r.si_faux.trim() });
+    }
+    return out;
+}
+/** Une fiche déjà écrite ne dispense de la spec que si elle passe les contrôles du programme et ne porte aucune hypothèse coûteuse. */
+export function ficheReady(repo, fiche, lot) {
+    if (checkSpec(repo, fiche, lot).length)
+        return false;
+    try {
+        return costlyHypotheses(parse(readFileSync(join(repo, fiche), 'utf8'))).length === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** Consigne de reprise après la réponse du lead à des hypothèses coûteuses : la règle confirmée n'est plus une hypothèse. */
+export function answeredText(asked, answer) {
+    return [
+        'The program asked the lead about expensive-to-undo hypotheses of your sheet:',
+        ...asked.map((q) => `- ${q}`),
+        `Answer from the lead: ${answer}`,
+        'Apply it to the sheet: a rule the lead confirms becomes `statut: sourcee` with `source: réponse du lead` (no `si_faux`); a rule the lead corrects is rewritten as they say (`sourcee`, same source). Do not leave it as `hypothese`, or the program asks the same question again.',
+    ].join('\n');
+}
+/** Fichiers suivis par git sous un dossier (chemins relatifs au dépôt). */
+function tracked(repo, dir) {
+    try {
+        return new Set(execFileSync('git', ['ls-files', '-z', '--', dir], { cwd: repo, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).split('\0').filter(Boolean));
+    }
+    catch {
+        return new Set();
+    }
+}
+/**
+ * Les écarts de la spec écrite par la session, relevés par le programme (vide = acceptée) : la fiche passe `cadence spec check`,
+ * elle est celle du lot et de son dossier, la maquette existe avec une section `#etat-<état>` par état et un
+ * `data-testid` par champ, et chaque état a sa capture à chaque largeur — le tout commité.
+ */
+export function checkSpec(repo, fiche, lot) {
+    const file = join(repo, fiche);
+    if (!existsSync(file))
+        return [`${fiche} : fiche absente (écrire docs/specs/<écran>/fiche.yaml et la commiter)`];
+    let doc;
+    try {
+        doc = parse(readFileSync(file, 'utf8'));
+    }
+    catch (e) {
+        return [`${fiche} : YAML illisible (${e.message.split('\n')[0]})`];
+    }
+    const problems = checkFiche(doc).map((p) => `fiche : ${p}`);
+    if (!isObj(doc) || !isObj(doc.ecran))
+        return problems;
+    const folder = fiche.replace(/\/fiche\.yaml$/, '');
+    const ecran = doc.ecran;
+    if (typeof ecran.lot === 'string' && ecran.lot !== lot)
+        problems.push(`ecran.lot : « ${ecran.lot} » au lieu de ${lot} (la fiche est celle du lot qui implémente l'écran)`);
+    if (typeof ecran.id === 'string' && !folder.endsWith(`/${ecran.id}`))
+        problems.push(`ecran.id : « ${ecran.id} » ne correspond pas au dossier ${folder}`);
+    const maquette = `${folder}/maquette.html`;
+    if (typeof ecran.maquette === 'string' && ecran.maquette !== maquette)
+        problems.push(`ecran.maquette : « ${ecran.maquette} » au lieu de ${maquette}`);
+    const git = tracked(repo, folder);
+    const need = (path, what) => {
+        if (!existsSync(join(repo, path)))
+            problems.push(`${path} : ${what} absent`);
+        else if (!git.has(path))
+            problems.push(`${path} : ${what} non commité`);
+    };
+    need(fiche, 'fiche');
+    need(maquette, 'maquette');
+    const html = existsSync(join(repo, maquette)) ? readFileSync(join(repo, maquette), 'utf8') : '';
+    const etats = Array.isArray(doc.etats) ? doc.etats.filter((e) => typeof e === 'string' && e.trim() !== '') : [];
+    if (html) {
+        for (const e of etats)
+            if (!new RegExp(`\\bid=["']etat-${e}["']`).test(html))
+                problems.push(`maquette.html : section id="etat-${e}" absente`);
+        for (const c of list(doc.champs))
+            if (typeof c.id === 'string' && !new RegExp(`data-testid=["']${c.id}["']`).test(html))
+                problems.push(`maquette.html : data-testid="${c.id}" absent (chaque champ de la fiche le porte)`);
+    }
+    for (const e of etats)
+        for (const w of LARGEURS)
+            need(`${folder}/maquette-${e}-${w}.png`, 'capture');
+    return problems;
+}
+/** 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 = [
+        `The lot declares \`screen: ${o.screen ?? 'page'}\`. 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.template)
+        lines.push('', 'Template of the sheet (`templates/fiche.yaml` of cadence; every key and invariant is checked by `cadence spec check`):', '```yaml', o.template.trimEnd(), '```');
+    if (o.problems?.length)
+        lines.push('', 'The program checked your previous spec and it did not pass; fix exactly these points (one more pass only, then the lot goes back to the lead):', ...o.problems.map((p) => `- ${p}`));
+    if (o.review)
+        lines.push('', o.review);
+    return lines.join('\n');
+}

package/dist/plan.js

@@ -5,7 +5,9 @@ import { isDay, toDay } from './dates.js';
 export const STATUSES = ['todo', 'doing', 'done', 'dropped'];
 export class RafError extends Error {
 }
-export const FIELDS = ['id', 'title', 'status', 'estimate', 'quickwin', 'visible', 'public', 'every', 'last', 'after', 'created', 'started', 'finished', 'notes', 'repos', 'parent'];
+export const FIELDS = ['id', 'title', 'status', 'estimate', 'quickwin', 'visible', 'screen', 'public', 'every', 'last', 'after', 'created', 'started', 'finished', 'notes', 'repos', 'parent'];
+/** Nature de l'écran d'un lot visible : nouvelle page, nouveau composant, parcours modifié. */
+export const SCREENS = ['page', 'component', 'journey'];
 export function isOpen(status) {
     return status === 'todo' || status === 'doing';
 }
@@ -290,6 +292,12 @@ export class Plan {
     }
     add(title, today, opts = {}) {
         this.writable();
+        if (opts.screen !== undefined) {
+            if (!SCREENS.includes(opts.screen))
+                throw new RafError(`screen inconnu : ${String(opts.screen)} (${SCREENS.join(', ')})`);
+            if (!opts.visible)
+                throw new RafError('--screen exige --visible : un écran est un changement visible');
+        }
         const known = new Set(this.lots().map((l) => l.id));
         for (const dep of opts.after ?? [])
             if (!known.has(dep))
@@ -309,6 +317,8 @@ export class Plan {
             entry.quickwin = true;
         if (opts.visible)
             entry.visible = true;
+        if (opts.screen)
+            entry.screen = opts.screen;
         if (opts.every !== undefined)
             entry.every = opts.every;
         if (opts.after?.length)
@@ -472,6 +482,7 @@ function foreignLots(raw, format) {
             estimate: typeof effort === 'string' ? format.estimates[effort] : effort,
             quickwin: pick('quickwin'),
             visible: pick('visible'),
+            screen: pick('screen'),
             public: pick('public'),
             every: pick('every'),
             last: day('last'),
@@ -519,6 +530,15 @@ function normalizeLot(raw, problems = []) {
     };
     const after = raw.after == null ? [] : Array.isArray(raw.after) ? raw.after.map(String) : [String(raw.after)];
     const last = asDay('last');
+    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`);
+    }
     return {
         id: String(raw.id),
         title: String(raw.title ?? ''),
@@ -526,6 +546,7 @@ function normalizeLot(raw, problems = []) {
         estimate: typeof raw.estimate === 'number' && raw.estimate > 0 ? raw.estimate : 1,
         quickwin: raw.quickwin === true,
         visible: raw.visible === true,
+        ...(screen ? { screen } : {}),
         ...(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/spec.js

@@ -0,0 +1,230 @@
+import { parse } from 'yaml';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { RafError } from './plan.js';
+/** Les largeurs de rendu d'une fiche (L170, spec etape-spec S2). */
+export const LARGEURS = [1440, 390];
+/** Les états qu'une fiche porte au moins. */
+export const ETATS_REQUIS = ['vide', 'chargement', 'erreur'];
+const KEBAB = /^[a-z][a-z0-9-]*$/;
+const APPEL = /^(GET|POST|PUT|PATCH|DELETE) \/\S*$/;
+const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const texte = (v) => typeof v === 'string' && v.trim() !== '';
+/**
+ * Les écarts d'une fiche d'écran aux invariants de la spec de l'étape spec (une phrase par écart ; vide = valide) :
+ * ids de champs uniques, règles R1… sans trou, statut et justification, états connus, tests « Rn — … »,
+ * citations d'ids existants (actions, règles, masque).
+ */
+export function checkFiche(doc) {
+    if (!isObj(doc))
+        return ["ce n'est pas une fiche : un document YAML à clés (ecran, etats, champs, regles, actions) est attendu"];
+    const p = [];
+    const ecran = isObj(doc.ecran) ? doc.ecran : {};
+    if (!isObj(doc.ecran))
+        p.push('ecran : bloc manquant');
+    for (const k of ['id', 'titre', 'route', 'lot', 'maquette'])
+        if (!texte(ecran[k]))
+            p.push(`ecran.${k} : texte attendu`);
+    if (texte(ecran.route) && !ecran.route.startsWith('/'))
+        p.push(`ecran.route : « ${ecran.route} » doit commencer par /`);
+    if (!Array.isArray(ecran.largeurs) || LARGEURS.some((w) => !ecran.largeurs.includes(w)))
+        p.push(`ecran.largeurs : [${LARGEURS.join(', ')}] attendu`);
+    const etats = Array.isArray(doc.etats) ? doc.etats.filter(texte) : [];
+    if (!Array.isArray(doc.etats))
+        p.push('etats : liste attendue');
+    else {
+        for (const [i, e] of doc.etats.entries())
+            if (!texte(e))
+                p.push(`état n° ${i + 1} : texte attendu`);
+        const manquants = ETATS_REQUIS.filter((e) => !etats.includes(e));
+        if (manquants.length)
+            p.push(`états : ${manquants.map((e) => `« ${e} »`).join(', ')} manquant(s) (vide, chargement et erreur sont requis)`);
+        for (const e of new Set(etats.filter((x, i) => etats.indexOf(x) !== i)))
+            p.push(`états : « ${e} » en double`);
+    }
+    const champs = Array.isArray(doc.champs) ? doc.champs : [];
+    if (champs.length === 0)
+        p.push('champs : liste non vide attendue');
+    const ids = new Set();
+    for (const [i, c] of champs.entries()) {
+        if (!isObj(c)) {
+            p.push(`champ n° ${i + 1} : objet attendu`);
+            continue;
+        }
+        const nom = texte(c.id) ? `« ${c.id} »` : `n° ${i + 1}`;
+        if (!texte(c.id))
+            p.push(`champ ${nom} : id manquant`);
+        else {
+            if (!KEBAB.test(c.id))
+                p.push(`champ ${nom} : l'id doit être en kebab-case (c'est aussi le data-testid)`);
+            if (ids.has(c.id))
+                p.push(`champ ${nom} en double`);
+            ids.add(c.id);
+        }
+        for (const k of ['libelle', 'type', 'source'])
+            if (!texte(c[k]))
+                p.push(`champ ${nom} : ${k} manquant`);
+        if (typeof c.obligatoire !== 'boolean')
+            p.push(`champ ${nom} : obligatoire doit valoir true ou false`);
+    }
+    const regles = Array.isArray(doc.regles) ? doc.regles : [];
+    if (regles.length === 0)
+        p.push('regles : liste non vide attendue');
+    const ruleIds = new Set();
+    for (const [i, r] of regles.entries()) {
+        const attendu = `R${i + 1}`;
+        if (!isObj(r)) {
+            p.push(`règle n° ${i + 1} : objet attendu`);
+            ruleIds.add(attendu);
+            continue;
+        }
+        const id = texte(r.id) ? r.id : attendu;
+        if (r.id !== attendu)
+            p.push(`règle n° ${i + 1} : l'id doit être ${attendu} (R1, R2… dans l'ordre, sans trou), pas ${texte(r.id) ? r.id : 'absent'}`);
+        ruleIds.add(id);
+        if (!texte(r.etat) || !etats.includes(r.etat))
+            p.push(`${id} : état « ${String(r.etat ?? '')} » inconnu (états : ${etats.join(', ')})`);
+        if (!texte(r.enonce))
+            p.push(`${id} : enonce manquant`);
+        if (!('message' in r) || !(r.message === null || typeof r.message === 'string'))
+            p.push(`${id} : message attendu (le texte exact à l'écran, ou null)`);
+        if (r.statut !== 'sourcee' && r.statut !== 'hypothese')
+            p.push(`${id} : statut « ${String(r.statut ?? '')} » inconnu (sourcee ou hypothese)`);
+        else if (r.statut === 'sourcee' && !texte(r.source))
+            p.push(`${id} : une règle sourcée dit d'où elle vient (source)`);
+        else if (r.statut === 'hypothese' && !texte(r.si_faux))
+            p.push(`${id} : une hypothèse dit ce qui changerait si elle était fausse (si_faux)`);
+        if ('champs' in r && r.champs !== undefined && r.champs !== null && !Array.isArray(r.champs))
+            p.push(`${id} : champs doit être une liste d'ids de champs`);
+        const cites = Array.isArray(r.champs) ? r.champs : [];
+        for (const c of cites)
+            if (!ids.has(String(c)))
+                p.push(`${id} : champ « ${String(c)} » absent de la fiche`);
+        if ('masque' in r && r.masque !== undefined && r.masque !== null) {
+            if (!Array.isArray(r.masque))
+                p.push(`${id} : masque doit être une liste d'ids de champs`);
+            else {
+                if (r.etat !== 'vide')
+                    p.push(`${id} : masque n'a de sens que pour une règle d'état « vide » (état « ${String(r.etat)} »)`);
+                for (const m of r.masque) {
+                    if (!ids.has(String(m)))
+                        p.push(`${id} : masque cite le champ « ${String(m)} » absent de la fiche`);
+                    else if (cites.includes(m))
+                        p.push(`${id} : masque cite « ${String(m)} » que la règle fait apparaître dans champs`);
+                }
+            }
+        }
+        const tests = Array.isArray(r.tests) ? r.tests : [];
+        if (tests.length === 0)
+            p.push(`${id} : au moins un test prévu, nommé « ${id} — … »`);
+        for (const t of tests)
+            if (typeof t !== 'string' || !t.startsWith(`${id} — `))
+                p.push(`${id} : le test « ${String(t)} » doit être nommé « ${id} — … »`);
+    }
+    const actions = Array.isArray(doc.actions) ? doc.actions : [];
+    if (!Array.isArray(doc.actions))
+        p.push('actions : liste attendue');
+    for (const [i, a] of actions.entries()) {
+        const attendu = `A${i + 1}`;
+        if (!isObj(a)) {
+            p.push(`action n° ${i + 1} : objet attendu`);
+            continue;
+        }
+        const id = texte(a.id) ? a.id : attendu;
+        if (a.id !== attendu)
+            p.push(`action n° ${i + 1} : l'id doit être ${attendu} (A1, A2… dans l'ordre), pas ${texte(a.id) ? a.id : 'absent'}`);
+        if (a.declencheur !== null && a.declencheur !== undefined && !(texte(a.declencheur) && ids.has(a.declencheur)))
+            p.push(`${id} : déclencheur « ${String(a.declencheur)} » absent de la fiche (un id de champ, ou null pour le chargement)`);
+        if (!texte(a.appel) || !APPEL.test(a.appel))
+            p.push(`${id} : appel « ${String(a.appel ?? '')} » invalide (VERBE /chemin)`);
+        if ('regles' in a && a.regles !== undefined && a.regles !== null && !Array.isArray(a.regles))
+            p.push(`${id} : regles doit être une liste d'ids de règles`);
+        for (const r of Array.isArray(a.regles) ? a.regles : [])
+            if (!ruleIds.has(String(r)))
+                p.push(`${id} : règle « ${String(r)} » absente de la fiche`);
+    }
+    return p;
+}
+/** Résumé d'une fiche valide, pour la sortie de `cadence spec check`. */
+export function summary(doc) {
+    const n = (k) => (Array.isArray(doc[k]) ? doc[k].length : 0);
+    const hyp = (Array.isArray(doc.regles) ? doc.regles : []).filter((r) => r.statut === 'hypothese').length;
+    return `fiche valide : ${n('champs')} champs, ${n('regles')} règles (${hyp} hypothèses), ${n('actions')} actions`;
+}
+/** Lit une fiche YAML ; un fichier absent ou illisible est une erreur d'usage (code 2), pas un écart de la fiche. */
+export function readFiche(path) {
+    if (!existsSync(path))
+        throw new RafError(`spec : fiche introuvable : ${path}`);
+    try {
+        return parse(readFileSync(path, 'utf8'));
+    }
+    catch (e) {
+        throw new RafError(`spec : ${path} n'est pas du YAML lisible : ${e.message.split('\n')[0]}`);
+    }
+}
+/** Une phrase sans point final, pour la suite d'un « unless » ou d'un « may be empty when ». */
+const condition = (enonce) => enonce.trim().replace(/[.\s]+$/, '');
+/**
+ * La section `docs/qa/expectations.md` de l'écran, dérivée de la fiche (spec etape-spec § 5). Une fiche invalide est refusée.
+ * - `shows:` un champ obligatoire par ligne, sauf les champs propres à un état (cités par une règle d'état vide ou erreur) ;
+ *   la ligne d'un champ du `masque` d'une règle sourcée d'état vide se termine par `— unless <énoncé>`.
+ * - `never:` les messages des règles d'état erreur (jamais celui d'une règle vide : c'est un affichage prévu).
+ * - `api:` les actions de chargement (sans déclencheur) en GET ; `— may be empty when <énoncé>` si une règle sourcée d'état vide la porte.
+ */
+export function deriveQa(doc) {
+    const problems = checkFiche(doc);
+    if (problems.length > 0)
+        throw new RafError(`fiche invalide :\n${problems.map((m) => `✗ ${m}`).join('\n')}`);
+    const f = doc;
+    const vides = f.regles.filter((r) => r.etat === 'vide' && r.statut === 'sourcee');
+    const propres = new Set(f.regles.filter((r) => r.etat === 'vide' || r.etat === 'erreur').flatMap((r) => r.champs ?? []));
+    const out = [`## ${f.ecran.route}`];
+    for (const c of f.champs.filter((x) => x.obligatoire === true && !propres.has(x.id))) {
+        const unless = vides.filter((r) => (r.masque ?? []).includes(c.id)).map((r) => condition(r.enonce));
+        out.push(`- shows: ${c.libelle}${unless.length ? ` — unless ${unless.join(' ; ')}` : ''}`);
+    }
+    const messages = f.regles.filter((r) => r.etat === 'erreur' && typeof r.message === 'string' && r.message !== '').map((r) => `"${r.message}"`);
+    if (messages.length)
+        out.push(`- never: ${messages.join(', ')}`);
+    for (const a of f.actions.filter((x) => (x.declencheur === null || x.declencheur === undefined) && x.appel.startsWith('GET '))) {
+        const peut = vides.filter((r) => (a.regles ?? []).includes(r.id)).map((r) => condition(r.enonce));
+        out.push(`- api: ${a.appel.slice(4)}${peut.length ? ` — may be empty when ${peut.join(' ; ')}` : ''}`);
+    }
+    return `${out.join('\n')}\n`;
+}
+/**
+ * Les règles `hypothese` des fiches du dossier des specs (`<dir>/<écran>/fiche.yaml`), par lot (`ecran.lot`) — L174.
+ * Un lot sans hypothèse n'y figure pas ; un dossier absent ou une fiche illisible ne donnent rien (le contrôle des fiches est `cadence spec check`).
+ */
+export function ficheHypotheses(root, dir) {
+    const out = new Map();
+    for (const { doc } of fichesDuDossier(root, dir)) {
+        if (!isObj(doc.ecran) || !texte(doc.ecran.lot))
+            continue;
+        const ids = (Array.isArray(doc.regles) ? doc.regles : []).filter(isObj).filter((r) => r.statut === 'hypothese' && texte(r.id)).map((r) => String(r.id));
+        if (ids.length)
+            out.set(doc.ecran.lot, [...(out.get(doc.ecran.lot) ?? []), ...ids]);
+    }
+    return out;
+}
+/** Les fiches lisibles de `<dir>/<écran>/fiche.yaml` (écrans triés), avec le nom du dossier : une fiche absente ou illisible est sautée. */
+export function fichesDuDossier(root, dir) {
+    const base = join(root, dir);
+    const out = [];
+    if (!existsSync(base))
+        return out;
+    for (const name of readdirSync(base).sort()) {
+        const file = join(base, name, 'fiche.yaml');
+        if (!existsSync(file))
+            continue;
+        try {
+            const doc = parse(readFileSync(file, 'utf8'));
+            if (isObj(doc))
+                out.push({ name, doc });
+        }
+        catch {
+            // fiche illisible : le contrôle des fiches est `cadence spec check`
+        }
+    }
+    return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sylad/cadence",
-  "version": "0.28.0",
+  "version": "1.1.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",
@@ -26,6 +26,7 @@
     "build": "tsc -p tsconfig.build.json",
     "test": "vitest run",
     "typecheck": "tsc --noEmit",
+    "eval:plugin": "claude plugin eval . --max-cost-usd 5 --no-publish",
     "prepare": "npm run build",
     "prepublishOnly": "npm run typecheck && npm test"
   },