@sylad/cadence 1.0.0 → 1.2.0

package/dist/orchestrate/fiche.js

@@ -0,0 +1,22 @@
+import { bulletLines } from './maquette.js';
+// Revue de la fiche back (L188, spec etape-spec-back B3) : ce que le programme dit à l'agent code-reviewer en mode « fiche », et à l'agent spec à la seconde passe.
+/** Consigne de la revue de fiche dans le brief : la fiche, la passe en cours, les points de la première revue à la seconde. */
+export function ficheReviewText(o) {
+    const second = o.passes >= 1;
+    const lines = [
+        `Sheet mode: review the sheet \`${o.fiche}\` (back part: \`sujet\`, \`cas\`, \`regles\`, \`contrats\`, \`donnees\`). It is a document, not code: read it, then open the code, the tests and the sources it cites.`,
+        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 sheet again.'
+            : 'This is the first review of this sheet.',
+    ];
+    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 des revues de la fiche (et de la maquette d'un lot mixte), ensemble. */
+export function reviewedSheetText(constats, mockup) {
+    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:`,
+        ...bulletLines(constats),
+    ].join('\n');
+}

package/dist/orchestrate/launch.js

@@ -4,35 +4,38 @@ 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` quand il a un écran `screen:` (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)))))
+export function mcpServersFor(kind, visible, outputDir, small = false, screen = true) {
+    if (!(kind === 'ux' || kind === 'maquette' || (visible && ((kind === 'spec' && screen) || 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) {
     return join(resolve(lotDir), 'playwright');
 }
 /** Écrit `<lotDir>/mcp-<étape>.json` (et, si Playwright est chargé, le dossier `playwright/`) ; rend le chemin absolu du fichier. */
-export function writeMcpConfig(lotDir, kind, visible, small = false) {
+export function writeMcpConfig(lotDir, kind, visible, small = false, screen = true) {
     const dir = resolve(lotDir);
     const out = playwrightDir(dir);
-    const servers = mcpServersFor(kind, visible, out, small);
+    const servers = mcpServersFor(kind, visible, out, small, screen);
     if (servers.playwright)
         mkdirSync(out, { recursive: true });
     const file = join(dir, `mcp-${kind}.json`);
     writeFileSync(file, `${JSON.stringify({ mcpServers: servers }, null, 2)}\n`);
     return file;
 }
-/** Outils interdits à toute session : pas de sous-agent, pas de push, de livraison ni de verdict. */
-export const DISALLOWED = ['Agent', 'Bash(git push:*)', 'Bash(cadence deliver:*)', 'Bash(raf done:*)', 'Bash(raf review:*)', 'Bash(raf ux:*)'];
+/** Outils interdits à toute session : pas de sous-agent, pas de push, de livraison, de verdict ni de rescellé d'un test d'acceptation (le chemin du lead, L200). */
+export const DISALLOWED = ['Agent', 'Bash(git push:*)', 'Bash(cadence deliver:*)', 'Bash(raf done:*)', 'Bash(raf review:*)', 'Bash(raf ux:*)', 'Bash(cadence spec reseal:*)', 'Bash(raf spec reseal:*)'];
 /** Outils MCP du serveur Playwright, par le préfixe du serveur (sonde réelle du 07-10 : `mcp__playwright` expose tous les `browser_*`). */
 export const PLAYWRIGHT_TOOLS = 'mcp__playwright';
 /** Agents passés à `--agents` : l'agent d'une étape qui charge Playwright, s'il a une liste d'outils, y gagne les outils du serveur (sinon il ne peut pas l'appeler). */
@@ -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,197 @@
+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 ou sujet>/fiche.yaml` (`ecran.lot` ou `sujet.lot`), 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) || (isObj(doc.sujet) && doc.sujet.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;
+}
+/** La fiche écrite porte une partie back (un bloc `sujet`) : c'est ce qui fait d'un lot à `screen:` un lot mixte (L188), jamais un champ `spec: true` à côté de `screen:`. */
+export function ficheHasBack(repo, fiche) {
+    try {
+        const doc = parse(readFileSync(join(repo, fiche), 'utf8'));
+        return isObj(doc) && 'sujet' in doc;
+    }
+    catch {
+        return false;
+    }
+}
+/** 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, parts = { screen: true, back: false }) {
+    if (checkSpec(repo, fiche, lot, parts).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, parts = { screen: true, back: false }) {
+    const file = join(repo, fiche);
+    if (!existsSync(file))
+        return [`${fiche} : fiche absente (écrire ${fiche.replace(/[^/]+\/fiche\.yaml$/, parts.screen ? '<écran>' : '<sujet>')}/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))
+        return problems;
+    const folder = fiche.replace(/\/fiche\.yaml$/, '');
+    // un lot back (`spec: true`, avec ou sans écran) écrit la partie sujet : sans elle, ni lot ni dossier ne seraient contrôlés
+    if (parts.back) {
+        if (!isObj(doc.sujet)) {
+            if (!('sujet' in doc) && 'ecran' in doc)
+                problems.push('fiche : sujet : bloc manquant (un lot qui change un comportement écrit la partie sujet, même si la fiche a aussi un écran)');
+        }
+        else {
+            const sujet = doc.sujet;
+            if (typeof sujet.lot === 'string' && sujet.lot !== lot)
+                problems.push(`sujet.lot : « ${sujet.lot} » au lieu de ${lot} (la fiche est celle du lot qui implémente le comportement)`);
+            if (typeof sujet.id === 'string' && !folder.endsWith(`/${sujet.id}`))
+                problems.push(`sujet.id : « ${sujet.id} » ne correspond pas au dossier ${folder}`);
+            if (!parts.screen && !tracked(repo, folder).has(fiche))
+                problems.push(`${fiche} : fiche non commité`);
+        }
+    }
+    if (!parts.screen)
+        return problems;
+    // un lot à écran écrit la partie écran : sans elle, ni lot, ni dossier, ni maquette, ni captures ne seraient contrôlés
+    if (!isObj(doc.ecran))
+        return [...problems.filter((p) => p !== 'fiche : ecran : bloc manquant'), 'fiche : ecran : bloc manquant (un lot à écran écrit la partie écran, même si la fiche a aussi un sujet)'];
+    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;
+}
+/** Première phrase d'un texte, ramenée à une longueur lisible dans une note. */
+const sentence = (t, max = 160) => {
+    const flat = t.replace(/\s+/g, ' ').trim();
+    const end = flat.search(/[.!?](\s|$)/);
+    const first = end > 0 ? flat.slice(0, end) : flat;
+    return first.length > max ? `${first.slice(0, max - 1).trimEnd()}…` : first;
+};
+/** Une ligne par règle `hypothese` de la fiche (`R3 : ce que la règle dit ; si faux : ce qui changerait`), pour la note du lot et le tableau de fin de vague (spec etape-spec-back § 7). */
+export function hypothesisLines(doc) {
+    if (!isObj(doc))
+        return [];
+    return list(doc.regles)
+        .filter((r) => r.statut === 'hypothese' && typeof r.id === 'string')
+        .map((r) => `${String(r.id)} : ${sentence(String(r.enonce ?? ''))} ; si faux : ${sentence(String(r.si_faux ?? ''))}`);
+}
+/** Texte de la note du lot pour une hypothèse (une note par règle). */
+export const hypothesisNote = (sujet, line) => `Hypothèses (fiche ${sujet}) — ${line}`;
+/** Consigne propre à l'étape spec dans le brief : dossier, largeurs, commande de rendu, et les écarts de la passe précédente. */
+export function specText(o) {
+    const lines = [];
+    if (o.screen) {
+        lines.push(`The lot declares \`screen: ${o.screen}\`. The specs of this project live in \`${o.dir}/<écran>/\` (one folder per screen, \`<écran>\` = the kebab-case \`ecran.id\` of the sheet).`, `Render each state of the mockup at ${LARGEURS.map((w) => `${w}`).join(' and ')} px width: one capture per state and per width, named \`maquette-<état>-<largeur>.png\` (e.g. \`maquette-vide-1440.png\`).`, o.render
+            ? `The project declares how to render mockups (\`orchestrate.spec.render\`): \`${o.render}\` (from the repository root). Use it; fall back on Playwright only if it cannot run, and say so under "nonVerifie".`
+            : 'No render command is declared (`orchestrate.spec.render`): render with Playwright (open `maquette.html` as a local file, resize to each width, open each `#etat-<état>`).');
+    }
+    if (o.back) {
+        lines.push(o.screen
+            ? `The sheet has both parts, \`sujet\`, \`cas\`, \`contrats\`, \`donnees\` next to \`ecran\`, in the same folder (\`sujet.id\` = \`ecran.id\` = the folder name, \`sujet.lot\` = \`ecran.lot\`); the API calls of the screen are listed once in \`contrats\`, and the actions point to them with \`contrat: Ax\`.`
+            : `The lot declares \`spec: true\` (it changes a behaviour, with no screen). The specs of this project live in \`${o.dir}/<sujet>/\` (one folder per subject, \`<sujet>\` = the kebab-case \`sujet.id\` of the sheet); the sheet has no screen part.`);
+    }
+    if (o.screen && !o.back) {
+        lines.push(`If the lot also changes a behaviour (an API call, a stored datum, a contract), add the back part to the same sheet: \`sujet\`, \`cas\`, \`contrats\`, \`donnees\` next to \`ecran\` (\`sujet.id\` = \`ecran.id\` = the folder name, \`sujet.lot\` = \`ecran.lot\`); the program then also has the sheet reviewed (rules sourced, contradictions, errors and limits, one test per rule), before the mockup. A lot that only draws a screen keeps a sheet without \`sujet\`.`);
+    }
+    if (o.template)
+        lines.push('', 'Template of the screen part of the sheet (`templates/fiche.yaml` of cadence; every key and invariant is checked by `cadence spec check`):', '```yaml', o.template.trimEnd(), '```');
+    if (o.templateBack)
+        lines.push('', 'Template of the back part of the sheet (`templates/fiche-back.yaml` of cadence; every key and invariant is checked by `cadence spec check`):', '```yaml', o.templateBack.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/orchestrate/state.js

@@ -11,8 +11,8 @@ export const lotRepoPaths = (l) => [l.repo, ...(l.repos ?? []).map((r) => r.path
 /** Les dépôts voisins du lot, donnés en `--add-dir` à ses sessions. */
 export const neighbourDirs = (l) => (l.repos ?? []).map((r) => r.path);
 export const lotKey = (project, lot) => `${project}:${lot}`;
-/** Nom de dossier d'un lot dans la vague : le « / » d'un id de sous-tâche (`Q4/accueil-4-ux12`) devient « __ » ; un id sans « / » est inchangé. */
-export const lotSlug = (project, lot) => `${project}--${lot.split('/').join('__')}`;
+/** Nom de dossier d'un lot dans la vague : le « / » d'un id de sous-tâche (`Q4/accueil-4-ux12`) ou d'un projet imbriqué (`groupe/gamma`) devient « __ » ; sans « / » le nom est inchangé. */
+export const lotSlug = (project, lot) => `${project.split('/').join('__')}--${lot.split('/').join('__')}`;
 const lotFile = (project, lot) => `${lotSlug(project, lot)}.json`;
 function atomicWrite(file, data) {
     const tmp = `${file}.${process.pid}.tmp`;

package/dist/orchestrate/table.js

@@ -123,6 +123,8 @@ export function renderTable(wave, lots, deps = {}) {
             out.push(`${l.project}:${l.lot} — ⚠ ${w}`);
         for (const x of l.choix ?? [])
             out.push(`${l.project}:${l.lot} — choix fait : ${x}`);
+        for (const h of l.hypotheses ?? [])
+            out.push(`${l.project}:${l.lot} — hypothèse de la fiche : ${h}`);
         for (const p of l.proposals)
             out.push(`${l.project}:${l.lot} — proposé : ${p}`);
         if (l.uxVerdict && l.visible)

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', 'spec', '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,10 @@ export class Plan {
             entry.quickwin = true;
         if (opts.visible)
             entry.visible = true;
+        if (opts.screen)
+            entry.screen = opts.screen;
+        if (opts.spec)
+            entry.spec = true;
         if (opts.every !== undefined)
             entry.every = opts.every;
         if (opts.after?.length)
@@ -404,6 +416,51 @@ export class Plan {
         const at = node.items.findIndex((p) => String(p.key?.value ?? p.key) === 'title');
         node.items.splice(at + 1, 0, this.doc.createPair('public', value));
     }
+    /** Pose, remplace (nature) ou retire (null) le `screen:` d'un lot existant ; exige `visible`, comme `add`. */
+    setScreen(ref, screen) {
+        this.writable();
+        if (ref.includes('/'))
+            throw new RafError(`l'écran se pose sur un lot, pas une sous-tâche : ${ref}`);
+        const node = this.lotNode(ref);
+        if (screen === null) {
+            node.delete('screen');
+            return;
+        }
+        if (!SCREENS.includes(screen))
+            throw new RafError(`screen inconnu : ${String(screen)} (${SCREENS.join(', ')}, none)`);
+        if (this.lot(ref).visible !== true)
+            throw new RafError(`${ref} n'est pas visible : un écran est un changement visible (raf add --visible)`);
+        if (node.has('screen')) {
+            node.set('screen', screen);
+            return;
+        }
+        const keys = node.items.map((p) => String(p.key?.value ?? p.key));
+        node.items.splice(keys.indexOf('visible') + 1, 0, this.doc.createPair('screen', screen));
+    }
+    /** Pose (true) ou retire (false) le `spec:` d'un lot existant ; `screen:` l'implique, donc on ne retire pas la spec d'un lot à écran. Renvoie false quand `screen:` rendait la pose sans objet. */
+    setSpec(ref, on) {
+        this.writable();
+        if (ref.includes('/'))
+            throw new RafError(`la spec se pose sur un lot, pas une sous-tâche : ${ref}`);
+        const node = this.lotNode(ref);
+        if (this.lot(ref).screen) {
+            if (!on)
+                throw new RafError(`${ref} a screen: — retirer d'abord screen: (raf screen ${ref} none), l'écran implique la spec`);
+            return false;
+        }
+        if (!on) {
+            node.delete('spec');
+            return true;
+        }
+        if (node.has('spec')) {
+            node.set('spec', true);
+            return true;
+        }
+        const keys = node.items.map((p) => String(p.key?.value ?? p.key));
+        const at = Math.max(...['screen', 'visible', 'quickwin', 'estimate'].map((k) => keys.indexOf(k)));
+        node.items.splice(at + 1, 0, this.doc.createPair('spec', true));
+        return true;
+    }
     /** Un lot récurrent a été refait : `last` passe à aujourd'hui, avec une note si `text` est donné. */
     did(ref, today, text) {
         this.writable();
@@ -472,6 +529,9 @@ function foreignLots(raw, format) {
             estimate: typeof effort === 'string' ? format.estimates[effort] : effort,
             quickwin: pick('quickwin'),
             visible: pick('visible'),
+            screen: pick('screen'),
+            // Le `spec:` d'un plan tenu par un autre outil n'est à nous que s'il est mappé, et seul `true` compte : ailleurs c'est souvent un chemin de document (L198).
+            spec: format.fields.spec && pick('spec') === true ? true : undefined,
             public: pick('public'),
             every: pick('every'),
             last: day('last'),
@@ -519,6 +579,22 @@ 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`);
+    }
+    let spec;
+    if (raw.spec != null) {
+        if (raw.spec === true)
+            spec = true;
+        else if (raw.spec !== false)
+            problems.push(`spec : true ou false attendu (reçu « ${String(raw.spec)} »)`);
+    }
     return {
         id: String(raw.id),
         title: String(raw.title ?? ''),
@@ -526,6 +602,8 @@ 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 } : {}),
+        ...(spec ? { spec } : {}),
         ...(typeof raw.public === 'string' && raw.public.trim() !== '' ? { public: raw.public.trim() } : {}),
         ...(Number.isInteger(raw.every) && raw.every > 0 ? { every: raw.every } : {}),
         ...(last ? { last } : {}),