@sylad/cadence 1.16.1 → 1.17.0

package/.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
     {
       "name": "cadence",
       "description": "Session start and close rituals driven by a versioned plan (raf), and deliveries proven by their effect. Needs the cadence CLI (npm i -g @sylad/cadence).",
-      "version": "1.16.1",
+      "version": "1.17.0",
       "source": "./",
       "author": {
         "name": "Sylvain Ladoire"

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "cadence",
   "description": "A repo-native working method: session start and close rituals driven by a versioned plan (raf), deliveries proven by their effect, and three reviewer agents (UX, code, QA).",
-  "version": "1.16.1",
+  "version": "1.17.0",
   "author": { "name": "Sylvain Ladoire" },
   "homepage": "https://github.com/Sylad/cadence",
   "repository": "https://github.com/Sylad/cadence",

package/dist/cli.js

@@ -62,7 +62,7 @@ const HELP = `raf — plan « reste à faire » versionné dans le dépôt, reli
   raf list [--status todo|doing|done|dropped]
   raf check [--since date] [--idle 7]   (défaut : date « since » du plan) code 1 s'il y a des écarts
   raf ignore <sha> | "<sujet exact>" [--reason texte]   acquitte un commit sans lot, citant un id inconnu ou des lots sans y travailler, sans réécrire l'historique ; raf check --ignored les liste
-  raf docs-ok <lot> --reason texte   acquitte l'écart docs.sync d'un lot (documentation en retard) avec la raison pour laquelle la documentation reste telle quelle ; lu par raf check et par orchestrate, qui ne rend jamais prêt un lot avec un écart ouvert
+  raf docs-ok <lot> --reason texte   acquitte l'écart docs.sync d'un lot (documentation en retard) avec la raison pour laquelle la documentation reste telle quelle (plan en lecture seule : .cadence/docs-ok.yaml, le plan n'est pas touché) ; lu par raf check et par orchestrate, qui ne rend jamais prêt un lot avec un écart ouvert
   raf gantt [-o .cadence/gantt.html]
   cadence config set <clé> <valeur> --all [--dry-run] [--depth n]   pose la même clé dans le cadence.yaml de chaque projet du dossier (ceux de lead tour), commentaires et ordre gardés, un lot de config qui la cite (raf add + start) et un commit à chemin explicite par projet ; ne pousse pas ; liste ce qui est fait et sauté (dépôt sale, déjà posée, plan en lecture seule) ; s'arrête sur une config qui ne se relit pas
   raf migrate [--dry-run]   déplace docs/plan/raf.yaml vers .cadence/raf.yaml (git mv) et réécrit les lecteurs du chemin dans le dépôt ; --dry-run les liste sans rien toucher ; refus tant qu'un lecteur n'est pas traité (migrate.keep de cadence.yaml pour ceux qui ne lisent pas le plan) ; rejouable
@@ -642,8 +642,13 @@ function dispatch(argv, io) {
             const plan = loadPlan();
             knownLot(plan, rest[0], 'docs-ok se pose sur un lot, pas sur une sous-tâche');
             plan.setDocsOk(rest[0], values.reason ?? '', today);
-            plan.save();
-            io.out(`${rest[0]} : écart docs.sync acquitté`);
+            // Un plan en lecture seule n'est pas écrit : l'acquittement est dans .cadence/docs-ok.yaml, à commiter à la place du plan (L386).
+            if (plan.readonly)
+                io.out(`${rest[0]} : écart docs.sync acquitté dans .cadence/docs-ok.yaml (le plan n'est pas touché) — commiter ce fichier`);
+            else {
+                plan.save();
+                io.out(`${rest[0]} : écart docs.sync acquitté`);
+            }
             return 0;
         }
         case 'check': {

package/dist/git.js

@@ -1,5 +1,5 @@
 import { execFileSync } from 'node:child_process';
-import { rmSync } from 'node:fs';
+import { rmSync, writeFileSync } from 'node:fs';
 import { basename, dirname, resolve } from 'node:path';
 function git(cwd, args) {
     // Le journal complet d'un gros dépôt dépasse le Mo par défaut : sans marge, il serait lu comme vide.
@@ -268,6 +268,27 @@ export function restorePaths(root, paths) {
             rmSync(resolve(root, f), { force: true });
     }
 }
+/**
+ * Remet `paths` comme à HEAD dans l'arbre de travail seulement, sans toucher à l'index : possible quand un `index.lock` bloque
+ * tout ce qui l'écrit (`restorePaths`, `git checkout`). Un fichier que HEAD ne connaît pas est supprimé.
+ */
+export function restoreWorktree(root, paths) {
+    for (const f of paths) {
+        let text;
+        try {
+            text = execFileSync('git', ['show', `HEAD:${f}`], { cwd: root, stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 1024 * 1024 * 1024 });
+        }
+        catch {
+            rmSync(resolve(root, f), { force: true });
+            continue;
+        }
+        writeFileSync(resolve(root, f), text);
+    }
+}
+/** Chemin du verrou de l'index de `repo` (`<git-dir>/index.lock`, celui du worktree s'il en est un). */
+export function indexLockPath(repo) {
+    return resolve(repo, git(repo, ['rev-parse', '--git-path', 'index.lock']).trim());
+}
 /** Un fichier SUIVI est-il modifié (indexé ou non) ? Les fichiers non suivis ne comptent pas : un commit à chemins explicites ne les embarque pas. `except` : chemins qu'on ne compte pas. */
 export function hasTrackedChanges(cwd, except = []) {
     return git(cwd, ['status', '--porcelain', '--untracked-files=no', '--', '.', ...except.map((f) => `:(exclude)${f}`)]).trim() !== '';

package/dist/orchestrate/command.js

@@ -27,7 +27,7 @@ import { costlyHypotheses, specScreen, specText } from './spec.js';
 import { fichesDuDossier } from '../spec.js';
 import { candidates, parsePriority, parseUntil, readPriority, stopReason } from './continue.js';
 import { precheckNothingToFind, Budget, ESCALATION_RESERVE, DROPPED, STOP_REQUESTED, MAX_PASSES, REVIEW_RESERVE, budgetStep, heldForEscalation, lotSpent, MAX_PASSES_CONVERGING, briefName, countInterrupted, planNoteHandBack, leadReviewedHandBack, HYPOTHESES_HANDBACK, handBackDroppedQuestions, needsPrecheck, workDir } from './cycle.js';
-import { canInstallPrePush, installPrePush, removePrePush, snapshot } from './guard.js';
+import { canInstallPrePush, gitProcessRunning, indexLockRefusal, installPrePush, longDuration, removePrePush, snapshot } from './guard.js';
 import { buildArgs, buildLocalArgs, killSessions, MODEL_ALIASES, mcpServersFor, readAgents, realClaude } from './launch.js';
 import { activeLock, REPO_LOCK, releaseLock, takeLock } from './lock.js';
 import { groupLots, runPool } from './pool.js';
@@ -344,6 +344,9 @@ async function preflight(args, targets, io, deps, launch, opts = {}) {
             const dirty = await trackedDirty(repo);
             if (dirty.length)
                 refusals.push(`${basename(repo)} : arbre sale, ${dirty.length} fichier(s) suivi(s) modifié(s) : ${dirty.join(', ')}`);
+            const locked = indexLockRefusal(repo, io.now(), deps.gitRunning ?? gitProcessRunning);
+            if (locked)
+                refusals.push(`${basename(repo)} : ${locked}`);
             const hook = canInstallPrePush(repo);
             if (hook)
                 refusals.push(`${basename(repo)} : ${hook}`);
@@ -604,16 +607,6 @@ export function liveLines(cap = DEFAULT_MAX_SESSIONS, now = new Date()) {
         lines.push(`  ${w.wave} (pid ${w.pid}, depuis ${w.started}) lancée depuis ${w.cwd} · plafond ${w.cap ?? '?'} · dépôts : ${w.repos.join(', ')}`);
     return lines;
 }
-/** Durée à la minute : « 12 min », « 5 h 10 min », « 2 j 3 h ». */
-function longDuration(ms) {
-    const m = Math.max(0, Math.floor(ms / 60_000));
-    if (m < 60)
-        return `${m} min`;
-    const h = Math.floor(m / 60);
-    if (h < 24)
-        return `${h} h ${String(m % 60).padStart(2, '0')} min`;
-    return `${Math.floor(h / 24)} j ${h % 24} h`;
-}
 /** Une ligne ⚠ par session du lead dont le TTL est échu et qui n'a pas été rendue (L278) : vide sans session échue. */
 export function expiredHoldLines(now = new Date()) {
     return expiredHolds(cadenceHome(), now).map((h) => {

package/dist/orchestrate/cycle.js

@@ -10,14 +10,14 @@ import { readDocsConfig, readPlanConfig } from '../config.js';
 import { PLAN_ACTIONS, leadAnswerMessage, planCommitMessage } from '../plan-commit.js';
 import { articleRepoDir, articlesBrief, docSyncBrief, docSyncGaps, filesOf, gapMessage } from '../docsync.js';
 import { testGateMissing } from '../testgate.js';
-import { changedFiles, dirtyPaths, gitCommonDir, isAncestor, readCommits, resolveCommit, restorePaths } from '../git.js';
+import { changedFiles, dirtyPaths, gitCommonDir, isAncestor, readCommits, resolveCommit, restoreWorktree, tryGit } from '../git.js';
 import { blockingLots, gitCommitsIn } from './table.js';
 import { citedRefs } from '../link.js';
 import { repoShas, repoWork } from '../repos.js';
 import { isOpen, RafError } from '../plan.js';
 import { isPlanOnly } from '../audit.js';
-import { compareBaseline, failedTests, hasUnnamedFailure, jestTestFiles } from './baseline.js';
-import { replayFile, replayRanFile, shellArg, TEST_WORKERS_ENV, testWorkersText } from './workers.js';
+import { compareBaseline, failedTests, hasUnnamedFailure } from './baseline.js';
+import { replayRed, TEST_WORKERS_ENV, testWorkersText } from './workers.js';
 import { APP_TIMEOUT_S, startApp } from './app.js';
 import { capturesText, headline, integrationText, localReading, newsText, objective, renderBrief, reposText, shotsText, TEMPLATES_DIR, tmpText } from './briefs.js';
 import { SlotAbandoned } from './registry.js';
@@ -154,18 +154,18 @@ async function commitPlan(c, message, root = c.lot.repo, before = new Map()) {
     const foreign = dirty.filter((f) => !ownFile(f));
     if (foreign.length)
         return `arbre sale (fichiers hors plan) : ${foreign.join(', ')}`;
-    git(repo, 'add', '--', ...dirty);
     try {
+        git(repo, 'add', '--', ...dirty);
         git(repo, 'commit', '-q', '-m', message, '--', ...dirty);
     }
     catch (e) {
-        // Commit refusé (hook commit-msg…, L343) : le plan n'a pas à rester indexé ni modifié par cadence, le lot suivant y verrait un dépôt sale et serait rendu.
+        // Commit refusé (hook commit-msg…, L343) ou index verrouillé (L385) : le plan n'a pas à rester indexé ni modifié par cadence, le lot suivant y verrait un dépôt sale et serait rendu.
         // Ce que le lead avait modifié sans commiter (raf add, raf note pendant la session) est remis, pas effacé.
-        git(repo, 'restore', '--staged', '--', ...dirty);
+        // Un index.lock bloque aussi la désindexation et le checkout : le désindexage est tenté sans plus, et l'arbre de travail est remis sans passer par l'index.
+        tryGit(repo, ['restore', '--staged', '--', ...dirty]);
         const own = dirty.filter((f) => !before.has(f));
-        // restorePaths : un fichier de plan.onWrite (L346) pas encore au dépôt est retiré, `git restore --source=HEAD` échouerait sur lui (pathspec) et laisserait le plan modifié.
         if (own.length)
-            restorePaths(repo, own);
+            restoreWorktree(repo, own);
         for (const [f, text] of before) {
             if (!dirty.includes(f))
                 continue;
@@ -550,9 +550,11 @@ function briefFor(c, kind, local = false) {
             vars.constats = constatLines(l.constats);
             if (l.docsFix) {
                 vars.elsewhere = articlesBrief(l.repo, docsConfig(c).articles ?? []);
-                vars.ack = wd(c) === l.repo
-                    ? `run \`raf docs-ok ${l.lot} --reason "why the documentation stays true"\` (a reason is required), then commit the plan file alone (\`git add -- .cadence/raf.yaml\`, or the path of the plan; message \`chore(${l.lot}): docs-ok\`).`
-                    : `this is a worktree, where only the program writes the plan: do not run \`raf docs-ok\` and do not touch the plan file. Make no commit and say under "choix" why the documentation stays true: the lot is handed back to the lead, who acknowledges it in the main checkout (\`raf docs-ok ${l.lot} --reason "…"\`).`;
+                vars.ack = wd(c) === l.repo && histPlan(c).readonly
+                    ? `run \`raf docs-ok ${l.lot} --reason "why the documentation stays true"\` (a reason is required): the plan is kept by another tool and is not written, the acknowledgement goes to \`.cadence/docs-ok.yaml\`; then commit that file alone (\`git add -- .cadence/docs-ok.yaml\`; message \`chore(${l.lot}): docs-ok\`).`
+                    : wd(c) === l.repo
+                        ? `run \`raf docs-ok ${l.lot} --reason "why the documentation stays true"\` (a reason is required), then commit the plan file alone (\`git add -- .cadence/raf.yaml\`, or the path of the plan; message \`chore(${l.lot}): docs-ok\`).`
+                        : `this is a worktree, where only the program writes the plan: do not run \`raf docs-ok\` and do not touch the plan file. Make no commit and say under "choix" why the documentation stays true: the lot is handed back to the lead, who acknowledges it in the main checkout (\`raf docs-ok ${l.lot} --reason "…"\`).`;
             }
         }
         else if (interrupted) {
@@ -2016,32 +2018,12 @@ async function programChecks(c, red, runs) {
         return;
     }
 }
-/** Sortie d'un lanceur qui n'a trouvé aucun test à rejouer : la ligne de fin du lanceur (vitest « No test files found, exiting with code », jest « No tests found, exiting with code », pytest « no tests ran in »), en début de ligne — pas ces mots cités dans le titre ou la sortie d'un test. */
-const NO_TEST_RAN = /^\W*(?:no test files? found, exiting with code|no tests? found, exiting with code|no tests ran in)\b/im;
-/** Rejeux d'un test rouge de la porte, seul (L354) : rouge aux deux, il est compté. */
-const REPLAYS = 2;
 /**
  * Rejoue SEULS (la commande `orchestrate.testReplay` où `{files}` devient les fichiers de ces tests, dans `cwd` : le worktree du lot, ou celui de la ligne de base) les tests rouges d'une suite entière (L354). Le 26-10, vitest à 31 workers par suite sur une machine à 4 sessions rougissait des tests
- * qui passaient seuls : quatre corrections vides (4 à 11 min chacune). Un test vert à un rejeu est `unstable` ; rouge aux `REPLAYS` rejeux, ou sans fichier désignable (rien à rejouer seul), il reste dans `red`.
+ * qui passaient seuls : quatre corrections vides (4 à 11 min chacune). Un test vert à un rejeu est `unstable` ; rouge aux rejeux, ou sans fichier désignable (rien à rejouer seul), il reste dans `red`. Le rejeu lui-même est `replayRed` (workers.ts), partagé avec `verify --gate` (L387).
  */
-async function replayAlone(c, template, names, output, cwd = wd(c)) {
-    const jest = jestTestFiles(output);
-    const fileOf = (n) => replayFile(n) ?? jest.get(n) ?? null;
-    let red = names;
-    const unstable = [];
-    for (let i = 0; i < REPLAYS; i++) {
-        const replayable = red.filter((n) => fileOf(n));
-        const files = [...new Set(replayable.map((n) => fileOf(n)))];
-        if (!files.length)
-            break;
-        const r = await sh(c, template.replaceAll('{files}', () => files.map(shellArg).join(' ')), undefined, undefined, cwd);
-        // Seul un rejeu qui sort en 0 en ayant exécuté le FICHIER du test vaut vert. Un rejeu en échec ne conclut rien pour un test qu'il ne nomme pas : sur une porte composée (`a && b`) les fichiers n'atteignent que le dernier lanceur, un premier lanceur qui rougit coupe avant lui. Un rejeu sans test exécuté (filtre sans fichier, `passWithNoTests`) sort en 0 sans rien prouver, et un lanceur qui ignore sans rien dire un fichier qu'il ne trouve pas (vitest d'un autre espace de travail) sort en 0 sans l'avoir joué : le fichier doit figurer, chemin entier, sur une ligne du lanceur de la sortie du rejeu, hors écho de la commande par npm/pnpm/yarn (`replayRanFile`).
-        const ran = r.code === 0 && !NO_TEST_RAN.test(r.output);
-        const passed = ran ? replayable.filter((n) => replayRanFile(r.output, fileOf(n))) : [];
-        unstable.push(...passed);
-        red = red.filter((n) => !passed.includes(n));
-    }
-    return { red, unstable };
+function replayAlone(c, template, names, output, cwd = wd(c)) {
+    return replayRed((command) => sh(c, command, undefined, undefined, cwd), template, names, output);
 }
 /** Trace des tests instables sous charge (L354) : le lot (`instables`, journal et `cadence perf`), un avertissement du lot (tableau de fin de vague) et une ligne du journal de la vague. */
 function noteUnstable(c, tests) {

package/dist/orchestrate/guard.js

@@ -1,8 +1,8 @@
-import { chmodSync, existsSync, lstatSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, lstatSync, readdirSync, statSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { execFile, execFileSync } from 'node:child_process';
 import { appendFileSync, mkdirSync } from 'node:fs';
 import { dirname, isAbsolute, join, relative } from 'node:path';
-import { gitCommonDir, gitRoot, hooksDir } from '../git.js';
+import { gitCommonDir, gitRoot, hooksDir, indexLockPath } from '../git.js';
 const MARK = '# cadence orchestrate — hook pre-push temporaire (retiré à la fin de la vague)';
 const waveLine = (wave) => `# wave: ${wave}`;
 const hook = (wave) => `#!/bin/sh
@@ -300,3 +300,45 @@ export function remoteAdvances(before, after) {
     const moved = [...now].filter(([ref, sha]) => was.get(ref) !== sha).map(([ref, to]) => ({ ref, from: was.get(ref) ?? null, to }));
     return moved.length > 0 ? moved : null;
 }
+/** Processus git en cours sur la machine ; null quand `ps` n'est pas lisible. */
+export function gitProcessRunning() {
+    try {
+        const out = execFileSync('ps', ['-A', '-o', 'comm='], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 10_000 });
+        return out.split('\n').some((l) => l.trim() === 'git');
+    }
+    catch {
+        return null;
+    }
+}
+/** Durée à la minute : « 12 min », « 5 h 10 min », « 2 j 3 h ». */
+export function longDuration(ms) {
+    const m = Math.max(0, Math.floor(ms / 60_000));
+    if (m < 60)
+        return `${m} min`;
+    const h = Math.floor(m / 60);
+    if (h < 24)
+        return `${h} h ${String(m % 60).padStart(2, '0')} min`;
+    return `${Math.floor(h / 24)} j ${h % 24} h`;
+}
+/**
+ * Un `index.lock` dans `repo` (L385) : tout commit y échoue, dont celui du plan au démarrage d'un lot, et le plan resterait modifié pour le lot suivant.
+ * Rend le refus (âge du verrou, processus git en cours ou non, commande pour le retirer), null s'il n'y en a pas. `gitRunning` : null = illisible.
+ */
+export function indexLockRefusal(repo, now, gitRunning) {
+    let lock;
+    let mtime;
+    try {
+        lock = indexLockPath(repo);
+        mtime = statSync(lock).mtime;
+    }
+    catch {
+        return null;
+    }
+    const hhmm = `${String(mtime.getHours()).padStart(2, '0')}:${String(mtime.getMinutes()).padStart(2, '0')}`;
+    const seen = `.git/index.lock présent depuis ${hhmm} (${longDuration(now.getTime() - mtime.getTime())})`;
+    const running = gitRunning();
+    if (running === true)
+        return `${seen}, un processus git tourne : attendre sa fin, puis relancer`;
+    const state = running === false ? 'aucun processus git en cours : verrou périmé' : 'processus git non vérifiable (ps illisible) : vérifier qu\'aucun ne tourne';
+    return `${seen}, ${state} ; le retirer avec \`rm ${lock}\` puis relancer`;
+}

package/dist/orchestrate/workers.js

@@ -1,5 +1,5 @@
 // Part de la machine de chaque session (L350) : le 26-10, 32 cœurs et 4 sessions, vitest à 31 workers par suite, et des tests qui passaient seuls rougissaient ensemble.
-import { stripAnsi } from './baseline.js';
+import { jestTestFiles, stripAnsi } from './baseline.js';
 /** Variable posée dans l'environnement des sessions et de la porte : le nombre de workers que leurs lanceurs de tests ont le droit d'ouvrir. */
 export const TEST_WORKERS_ENV = 'CADENCE_TEST_WORKERS';
 /** Cœurs ÷ plafond de sessions, arrondi vers le bas, jamais moins de 1 (cœurs inconnus ou plafond absurde compris). */
@@ -69,3 +69,30 @@ export function replayRanFile(output, file) {
         .split('\n')
         .some((line) => !LAUNCHER_ECHO.test(line) && re.test(line));
 }
+/** Sortie d'un lanceur qui n'a trouvé aucun test à rejouer : la ligne de fin du lanceur (vitest « No test files found, exiting with code », jest « No tests found, exiting with code », pytest « no tests ran in »), en début de ligne — pas ces mots cités dans le titre ou la sortie d'un test. */
+const NO_TEST_RAN = /^\W*(?:no test files? found, exiting with code|no tests? found, exiting with code|no tests ran in)\b/im;
+/** Rejeux d'un test rouge de la porte, seul (L354) : rouge aux deux, il est compté. */
+const REPLAYS = 2;
+/**
+ * Rejoue SEULS les tests `names` rouges dans `output` (L354, L387) : `run` exécute la commande `template` où `{files}` devient les fichiers de ces tests, dans le dossier de l'appelant (worktree du lot, de la ligne de base ou de `verify --gate`).
+ * Un test vert à un rejeu est `unstable` ; rouge aux `REPLAYS` rejeux, ou sans fichier désignable (rien à rejouer seul), il reste dans `red`.
+ */
+export async function replayRed(run, template, names, output) {
+    const jest = jestTestFiles(output);
+    const fileOf = (n) => replayFile(n) ?? jest.get(n) ?? null;
+    let red = names;
+    const unstable = [];
+    for (let i = 0; i < REPLAYS; i++) {
+        const replayable = red.filter((n) => fileOf(n));
+        const files = [...new Set(replayable.map((n) => fileOf(n)))];
+        if (!files.length)
+            break;
+        const r = await run(template.replaceAll('{files}', () => files.map(shellArg).join(' ')));
+        // Seul un rejeu qui sort en 0 en ayant exécuté le FICHIER du test vaut vert. Un rejeu en échec ne conclut rien pour un test qu'il ne nomme pas : sur une porte composée (`a && b`) les fichiers n'atteignent que le dernier lanceur, un premier lanceur qui rougit coupe avant lui. Un rejeu sans test exécuté (filtre sans fichier, `passWithNoTests`) sort en 0 sans rien prouver, et un lanceur qui ignore sans rien dire un fichier qu'il ne trouve pas (vitest d'un autre espace de travail) sort en 0 sans l'avoir joué : le fichier doit figurer, chemin entier, sur une ligne du lanceur de la sortie du rejeu, hors écho de la commande par npm/pnpm/yarn (`replayRanFile`).
+        const ran = r.code === 0 && !NO_TEST_RAN.test(r.output);
+        const passed = ran ? replayable.filter((n) => replayRanFile(r.output, fileOf(n))) : [];
+        unstable.push(...passed);
+        red = red.filter((n) => !passed.includes(n));
+    }
+    return { red, unstable };
+}

package/dist/plan.js

@@ -1,7 +1,7 @@
 import { spawnSync } from 'node:child_process';
 import { readFileSync, writeFileSync, mkdirSync, existsSync, rmSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
-import { isMap, isSeq, parseDocument } from 'yaml';
+import { dirname, join, resolve } from 'node:path';
+import { Document, isMap, isSeq, parseDocument } from 'yaml';
 import { isDay, toDay } from './dates.js';
 /** Délai de la commande `plan.onWrite` : une republication du plan, pas un build. */
 const ON_WRITE_TIMEOUT_MS = 120_000;
@@ -218,9 +218,9 @@ export class Plan {
     get configFile() {
         return this.settings.config ?? null;
     }
-    /** Fichiers tenus avec le plan, relatifs à la racine du dépôt. */
+    /** Fichiers tenus avec le plan, relatifs à la racine du dépôt (le fichier d'acquittement docs-ok d'un plan en lecture seule en est un, L386). */
     get files() {
-        return this.settings.files ?? [];
+        return [...(this.settings.files ?? []), ...(this.readonly && this.settings.config ? [DOCS_OK_FILE] : [])];
     }
     /** Fichiers que produit `plan.onWrite` (L346), relatifs à la racine du dépôt : à commiter avec le plan, même s'ils n'étaient pas encore suivis. */
     get produced() {
@@ -318,9 +318,15 @@ export class Plan {
         node.flow = true;
         this.lotNode(lotId).set(key, node);
     }
+    /** Chemin du fichier d'acquittement docs-ok d'un plan en lecture seule : `.cadence/docs-ok.yaml` à côté du cadence.yaml lu (L386) ; null sans cadence.yaml. */
+    get docsOkFile() {
+        return this.settings.config ? join(dirname(this.settings.config), DOCS_OK_FILE) : null;
+    }
     lots() {
-        if (this.settings.format)
-            return this.read().lots;
+        if (this.settings.format) {
+            const ack = readDocsOkFile(this.docsOkFile);
+            return this.read().lots.map((l) => (l.docsOk || !ack[l.id] ? l : { ...l, docsOk: ack[l.id] }));
+        }
         const raw = this.doc.get('lots').toJSON();
         return raw.map((r) => normalizeLot(r));
     }
@@ -400,12 +406,32 @@ export class Plan {
     }
     /** Acquitte l'écart `docs.sync` d'un lot (L317) : clé `docs_ok: { date, reason }`, la raison est obligatoire. Jamais sur une sous-tâche. */
     setDocsOk(ref, reason, today) {
-        this.writable();
         if (ref.includes('/'))
             throw new RafError(`docs-ok se pose sur un lot, pas sur une sous-tâche : ${ref}`);
         const why = reason.trim();
         if (!why)
             throw new RafError('docs-ok exige une raison : raf docs-ok <lot> --reason "pourquoi la documentation reste telle quelle"');
+        if (this.readonly) {
+            // Le plan est tenu par un autre outil : l'acquittement va dans un fichier de cadence, le plan n'est pas touché (L386).
+            const file = this.docsOkFile;
+            if (!file)
+                throw new RafError(`plan en lecture seule : ${this.path} est tenu par un autre outil — pas de cadence.yaml lu, donc pas de ${DOCS_OK_FILE} où acquitter`);
+            if (!this.lots().some((l) => l.id === ref))
+                throw new RafError(`lot inconnu : ${ref}`);
+            const doc = existsSync(file) ? parseDocument(readFileSync(file, 'utf8')) : new Document({});
+            if (doc.errors.length > 0)
+                throw new RafError(`${file} : ${doc.errors[0].message}`);
+            if (!isMap(doc.contents))
+                doc.contents = doc.createNode({});
+            const entry = doc.createNode({ date: today, reason: why });
+            entry.flow = true;
+            doc.set(ref, entry);
+            if (!existsSync(file))
+                doc.commentBefore = ' Écarts docs.sync acquittés (raf docs-ok) pour un plan tenu par un autre outil, lu par raf check et cadence orchestrate.';
+            mkdirSync(dirname(file), { recursive: true });
+            writeFileSync(file, doc.toString({ lineWidth: 0 }));
+            return;
+        }
         const node = this.doc.createNode({ date: today, reason: why });
         node.flow = true;
         this.lotNode(ref).set('docs_ok', node);
@@ -642,6 +668,28 @@ export class Plan {
     }
 }
 /** Lit une liste écrite dans un autre format : champs traduits, entrées à parent repliées en sous-tâches. */
+/** Fichier d'acquittement docs-ok d'un plan en lecture seule, relatif à la racine du dépôt (L386). */
+const DOCS_OK_FILE = '.cadence/docs-ok.yaml';
+/** Les acquittements du fichier : lot → { date, reason }. Une entrée sans raison n'acquitte rien ; un fichier illisible est une erreur qui le nomme. */
+function readDocsOkFile(file) {
+    if (!file || !existsSync(file))
+        return {};
+    const doc = parseDocument(readFileSync(file, 'utf8'));
+    if (doc.errors.length > 0)
+        throw new RafError(`${file} : ${doc.errors[0].message}`);
+    const raw = doc.toJSON();
+    if (raw == null)
+        return {};
+    if (typeof raw !== 'object' || Array.isArray(raw))
+        throw new RafError(`${file} : la racine doit être un objet (lot → { date, reason })`);
+    const out = {};
+    for (const [id, v] of Object.entries(raw)) {
+        const e = v;
+        if (e && typeof e === 'object' && typeof e.reason === 'string' && e.reason.trim() !== '')
+            out[id] = { date: String(e.date ?? ''), reason: e.reason.trim() };
+    }
+    return out;
+}
 function foreignLots(raw, format) {
     const entries = raw.map((r, i) => {
         if (!r || typeof r !== 'object' || Array.isArray(r))

package/dist/verify-gate.js

@@ -1,9 +1,11 @@
 import { spawn } from 'node:child_process';
 import { lstatSync, mkdtempSync, rmSync, unlinkSync } from 'node:fs';
-import { tmpdir } from 'node:os';
+import { availableParallelism, tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { onTermination } from './proc.js';
 import { failedTests, hasUnnamedFailure, unloadedSuites } from './orchestrate/baseline.js';
+import { configuredCap } from './orchestrate/command.js';
+import { replayRed, TEST_WORKERS_ENV, testWorkersFrom } from './orchestrate/workers.js';
 import { git, gitFailure, linkDeclared, linkIgnored } from './orchestrate/worktree.js';
 /** Délai de chaque commande de la porte : celui du rejeu de la ligne de base de la vague. */
 const GATE_TIMEOUT_MS = 30 * 60_000;
@@ -21,9 +23,9 @@ function killGroup(pgid) {
  * Une commande `sh -c` dans `cwd`, sortie standard et d'erreur réunies ; au délai, tout son groupe de processus est tué.
  * `group` reçoit le groupe en cours : le nettoyage d'un signal reçu par cadence le tue avant de retirer le worktree.
  */
-function sh(cmd, cwd, timeoutMs, group) {
+function sh(cmd, cwd, timeoutMs, group, env) {
     return new Promise((resolve) => {
-        const child = spawn('sh', ['-c', cmd], { cwd, stdio: ['ignore', 'pipe', 'pipe'], detached: true });
+        const child = spawn('sh', ['-c', cmd], { cwd, env, stdio: ['ignore', 'pipe', 'pipe'], detached: true });
         const pgid = child.pid;
         if (pgid === undefined) {
             child.once('error', (e) => resolve({ code: 127, output: e.message }));
@@ -50,6 +52,8 @@ function sh(cmd, cwd, timeoutMs, group) {
  * `cadence verify --gate` (L348) : la porte du projet (`orchestrate.build`, puis `orchestrate.test`, dans l'ordre de la vague : les tests lisent ce que le build produit)
  * rejouée au `sha` dans un worktree jetable, hors du dépôt, dont les dépendances non suivies sont reliées depuis le dépôt vivant (`orchestrate.worktreeDeps`,
  * sinon les dossiers ignorés de tout niveau, comme les worktrees de vague). Les deux commandes sont rejouées même si la première est rouge : le compte rendu est entier.
+ * Chaque commande reçoit `CADENCE_TEST_WORKERS` comme dans la porte d'une vague (L350, L387) : la valeur de l'environnement de l'appelant si c'est un entier positif, sinon cœurs ÷ plafond de sessions (`CADENCE_MAX_SESSIONS`, 2 par défaut) ;
+ * sans elle le rejeu `--maxWorkers=$CADENCE_TEST_WORKERS` de `orchestrate.testReplay` sortirait en erreur et ne prouverait rien.
  * Le worktree est retiré dans tous les cas. 0 vert, 1 rouge (avec les tests en échec), 2 rien à rejouer ou worktree impossible.
  */
 export async function verifyGate(ctx) {
@@ -59,6 +63,8 @@ export async function verifyGate(ctx) {
         ...(config.test ? [{ name: 'tests', cmd: config.test }] : []),
     ];
     const short = sha.slice(0, 7);
+    const base = ctx.env ?? process.env;
+    const env = { ...base, [TEST_WORKERS_ENV]: String(testWorkersFrom(base, ctx.cores ?? availableParallelism(), configuredCap(base))) };
     if (steps.length === 0) {
         out('verify --gate : ni orchestrate.test ni orchestrate.build déclarés dans cadence.yaml — rien à rejouer');
         return 2;
@@ -106,22 +112,47 @@ export async function verifyGate(ctx) {
         }
         let red = 0;
         for (const step of steps) {
-            const r = await sh(step.cmd, dir, ctx.timeoutMs ?? GATE_TIMEOUT_MS, group);
+            const r = await sh(step.cmd, dir, ctx.timeoutMs ?? GATE_TIMEOUT_MS, group, env);
             if (r.code === 0) {
                 out(`✓ ${step.name} (${step.cmd})`);
                 continue;
             }
-            red++;
-            out(`✗ ${step.name} (${step.cmd}) — code ${r.code}`);
             const tests = step.name === 'tests';
             const names = tests ? failedTests(r.output) : [];
             const unloaded = tests ? unloadedSuites(r.output) : [];
-            for (const n of names)
+            // `orchestrate.testReplay` comme la porte d'une vague (L354, L387) : un rouge nommé est rejoué seul avant d'être compté ; vert au rejeu, il est instable sous charge.
+            // Un échec que la sortie ne rattache à aucun test, ou un fichier qui ne se charge pas, n'est jamais rejoué.
+            const replayable = tests && config.testReplay && names.length > 0 && unloaded.length === 0 && !hasUnnamedFailure(r.output);
+            const replays = [];
+            const { red: still, unstable } = replayable
+                ? await replayRed(async (c) => {
+                    const p = await sh(c, dir, ctx.timeoutMs ?? GATE_TIMEOUT_MS, group, env);
+                    replays.push(p.code);
+                    return p;
+                }, config.testReplay, names, r.output)
+                : { red: names, unstable: [] };
+            if (replayable && still.length === 0) {
+                out(`✓ ${step.name} (${step.cmd}) — ${unstable.length} test(s) rouge(s) sous charge, verts rejoués seuls (instables sous charge) :`);
+                for (const n of unstable)
+                    out(`  - ${n}`);
+                continue;
+            }
+            red++;
+            out(`✗ ${step.name} (${step.cmd}) — code ${r.code}`);
+            for (const n of still)
                 out(`  - ${n}`);
             for (const n of unloaded)
                 out(`  - ${n} (ne se charge pas)`);
-            if (names.length + unloaded.length === 0 || hasUnnamedFailure(r.output, true)) {
-                if (names.length + unloaded.length)
+            // Un rejeu a eu lieu : dire lequel, pour qu'un rejeu en échec pour une autre raison qu'un vrai rouge (commande cassée, aucun test exécuté) ne passe pas pour une confirmation du rouge.
+            if (replays.length)
+                out(`  rejeu seul (orchestrate.testReplay) : ${replays.length} rejeu(x), dernier code ${replays[replays.length - 1]} — ${names.length - still.length} test(s) confirmé(s) vert(s) sur ${names.length} ; un rejeu en échec ou sans test exécuté ne prouve rien`);
+            if (unstable.length) {
+                out(`  ${unstable.length} autre(s) test(s) rouge(s) sous charge, verts rejoués seuls (instables sous charge) :`);
+                for (const n of unstable)
+                    out(`    - ${n}`);
+            }
+            if (still.length + unloaded.length === 0 || hasUnnamedFailure(r.output, true)) {
+                if (still.length + unloaded.length)
                     out('  (au moins un échec que la sortie ne rattache à aucun test)');
                 if (r.output.trim())
                     for (const l of r.output.trimEnd().split('\n').slice(-TAIL_LINES))

package/docs/deliver.md

@@ -305,8 +305,9 @@ verify --gate 6b0d9aa : rouge (1 étape sur 2)
 ```
 
 Both commands always run, even when the first is red, so the report is whole. A red step lists the failing
-tests the output names (the same reading as the wave's baseline) and the test files that do not load (`- test/a.test.ts (ne se charge pas)`, the typical sign of a missing dependency); with none identifiable, the last 10 lines of the output.
+tests the output names (the same reading as the wave's baseline) and the test files that do not load (`- test/a.test.ts (ne se charge pas)`, the typical sign of a missing dependency); with none identifiable (or when an unnamed failure is mixed with them), the last 10 lines of the output, each prefixed `  | `: a red that names no test, seen three times under load on 27-10 (L380, B28.17), is no longer a bare exit code.
+With `orchestrate.testReplay` declared (`docs/orchestrate.md`, « A red test is replayed alone »), the gate does what a wave does: a red test the output names is **replayed alone, twice at most**, in the same throwaway worktree. Green at a replay it is *unstable under load*: the step prints `✓ tests (…) — N test(s) rouge(s) sous charge, verts rejoués seuls (instables sous charge) :` with the names and does not make the gate red; the tests still red stay listed and the unstable ones follow, under a line of their own. A failure the output ties to no test, or a file that does not load, is never replayed and stays red. When a replay took place and the step stays red, one line says so (`rejeu seul (orchestrate.testReplay) : N rejeu(x), dernier code C — k test(s) confirmé(s) vert(s) sur n`): a replay that fails or runs no test confirms nothing, and the line tells a real red from a replay that could not run. Without `testReplay` nothing is replayed.
 Each command has 30 minutes (then its whole process group is killed, code 124). Ctrl-C, SIGTERM or a hangup received by cadence kills the running command and removes the worktree before cadence dies.
 `--sha` is required (the moving head of a wave is not a sha to re-verify) and `--retry` does not apply. Exit code:
 **0** green · **1** red · **2** nothing to replay (neither `orchestrate.build` nor `orchestrate.test`), unknown sha or a worktree that cannot be made.
-The Node of the `.nvmrc` is not selected here, and `CADENCE_TEST_WORKERS` is not set: the commands run with the environment of the caller (`PATH` included), so a re-verification run during a wave should export the session's `CADENCE_TEST_WORKERS` itself, or vitest takes every core.
+The Node of the `.nvmrc` is not selected here: the commands run with the environment of the caller (`PATH` included). `CADENCE_TEST_WORKERS` is set for the build, the tests and the replays, as a wave does (`docs/orchestrate.md`, L350): the value of the caller's environment when it is a positive integer, otherwise cores ÷ session cap (`CADENCE_MAX_SESSIONS`, 2 by default), so a `testReplay` such as `--maxWorkers=$CADENCE_TEST_WORKERS` works from a plain shell.

package/docs/orchestrate.md

@@ -38,6 +38,8 @@ cadence orchestrate --stop-after-current [--wave <wave>]   # from another termin
 
 **Claude Code must be installed and logged in** (L378). Before starting a lot, `cadence orchestrate` runs `claude auth status` (no model, no cost); when it says `loggedIn: false` the command is refused (exit 2) before anything is written: no `raf start`, no plan commit, the lot stays `todo`. The message says what to do: « claude n'est pas connecté : lancer `claude` puis /login (état : `claude auth status`) ». `--dry-run` starts no session, so it is not refused: it prints the same message after its first line, as a `⚠`. `claude auth status` is read once per launch, so with `--continue` the rounds of a wave do not run it again for every candidate lot. An unreadable answer (a `claude` without `auth status`) is not a refusal.
 
+**A stale `.git/index.lock` is refused up front** (L385). While the lock exists, every commit of the repository fails, the plan commit at the start of a lot included, and the plan would stay modified so that the next lot is handed back as a dirty repository. `cadence orchestrate` (and `--dry-run`, and `--resume`) therefore looks for `<git-dir>/index.lock` in each repository of the lot before writing anything, and refuses (exit 2): `<repo> : .git/index.lock présent depuis 13:46 (5 h 12 min), aucun processus git en cours : verrou périmé ; le retirer avec `rm <chemin>` puis relancer`. The process check is `ps`: when a `git` process is running the message says so and does not suggest removing the lock; when `ps` is unreadable it says the check could not be made. If a plan commit still fails during a wave (a lock taken after the start, a refusing hook), the plan is put back as it was, without going through the index, which the lock blocks: the lot fails, the next one finds a clean repository.
+
 A `<project>` is a sub-folder of the current folder. Launched from inside `alpha`, `alpha:L1` looks for `alpha/alpha` and is refused: `alpha:L1 : dossier …/alpha/alpha introuvable (le projet est un sous-dossier du dossier courant ; dans un dépôt, `.:L1`)` (L376). Inside a repository, `.:L1` or `L1` names the lot of the repository itself.
 
 **`--drop` and `--stop-after-current` — steering a running wave (L79)**: both are run from the folder the wave was launched
@@ -230,7 +232,7 @@ orchestrate:
 the commits of the lot touch code without touching the document that describes it, the lot goes to a documentation pass
 before its review: a `fix` session launched with the `doc-keeper` agent (`agents/doc-keeper.md`) and its own brief
 (`fix-docs`), which lists the lines the program computed and asks for the documents to be brought up to date, nothing else. The
-pass counts as one of the two correction passes and plays once per lot: if the librarian leaves the gap open — it commits no document, and has not acknowledged the gap with `raf docs-ok <lot> --reason "…"` (L317) — the lot is **handed back** (cause « documentation en retard (docs.sync) ») and the review does not play: a lot never ends ready while `raf check` reports a documentation gap. The same check runs at the end of the conforming review, for a lot whose librarian gate could not play (passes or budget used up). An acknowledged gap (`docs_ok:` on the lot, committed with the plan) is no gap: no pass, no finding in the review brief. In a lot's worktree (`orchestrate.worktrees`) only the program writes the plan: the librarian's brief there does not ask it to run `raf docs-ok` — it makes no commit and says why under "choix", the lot is handed back and the lead acknowledges in the main checkout; an acknowledgement the lead committed before the wave is read from the lead's plan (L320). It does not play during the minors pass, nor when a
+pass counts as one of the two correction passes and plays once per lot: if the librarian leaves the gap open — it commits no document, and has not acknowledged the gap with `raf docs-ok <lot> --reason "…"` (L317) — the lot is **handed back** (cause « documentation en retard (docs.sync) ») and the review does not play: a lot never ends ready while `raf check` reports a documentation gap. The same check runs at the end of the conforming review, for a lot whose librarian gate could not play (passes or budget used up). An acknowledged gap (`docs_ok:` on the lot, committed with the plan; for a read-only plan, an entry of `.cadence/docs-ok.yaml`, which the librarian's brief then names to commit instead of the plan, L386) is no gap: no pass, no finding in the review brief. In a lot's worktree (`orchestrate.worktrees`) only the program writes the plan: the librarian's brief there does not ask it to run `raf docs-ok` — it makes no commit and says why under "choix", the lot is handed back and the lead acknowledges in the main checkout; an acknowledgement the lead committed before the wave is read from the lead's plan (L320). It does not play during the minors pass, nor when a
 correction pass is already used (its pass would take the last one), nor when the lot budget no longer pays it and the review after
 it (a warning `bibliothécaire non appelé` says so each time; the review goes ahead). Without `docs.sync`, or with no gap: no pass.
 When the project's `cadence.yaml` declares `docs.articles` (the same key as the article refreshed after a delivery, see [news](news.md#an-article-elsewhere-that-follows-the-delivery)), the brief names those
@@ -841,7 +843,7 @@ News instruction (`cadence news new <lot>`, factual user-side text, a screenshot
 ```yaml
 orchestrate:
   test: npm test                         # run by the orchestrator after a work step (optional)
-  testReplay: npx vitest run --minWorkers=1 --maxWorkers=$CADENCE_TEST_WORKERS {files}   # replay alone of a red test before it counts (L354, see « A red test is replayed alone »); `{files}` required; absent: no replay, nothing held for unstable (optional)
+  testReplay: npx vitest run --minWorkers=1 --maxWorkers=$CADENCE_TEST_WORKERS {files}   # replay alone of a red test before it counts (L354, see « A red test is replayed alone »; `cadence verify --gate` applies it too, L387, `docs/deliver.md`); `{files}` required; absent: no replay, nothing held for unstable (optional)
   build: npm run build                   # run BEFORE the tests (L333); both results go to the reviewer, who does not redo them (optional)
   worktreeDeps: [node_modules, .venv]    # untracked dependencies that `cadence verify --gate` links into its throwaway worktree (L348, `docs/deliver.md`); absent: the ignored folders of every level, as the worktrees of a wave (optional)
   precheck: true                         # default: before the first implementation of a lot with no commit whose title cites a finding or an earlier lot, and whose title or `goal:` cites a finding (`constat`, `revue`, `review`, `audit`) or a plan id (an earlier `L<number>`, also followed by a hyphen as in `L12-L15` or `L12-bis`; any other id such as `Q-CAN5`; `project:L<number>`), a read-only Sonnet session checks whether the deliverable is already in the repository (see below); false skips it, local runs it on claude-local (Ollama) with Sonnet as fallback, for every lot with no commit whatever its title (L296); a lot created after the last code commit of the repository is not pre-checked, local or Sonnet, unless it cites a lot that already has commits (L322)

package/docs/raf.md

@@ -69,7 +69,7 @@ raf gantt                         # .cadence/gantt.html (next to the plan)
 | `raf commits <id>` | the commits counted for a lot (the set the code review gate uses), one `<sha> <subject>` per line, oldest first; a lot that declares `repos:` ([neighbouring repositories](orchestrate.md#a-lot-whose-work-is-in-a-neighbouring-repository)) gets, after them, one `dépôt <path> :` section per neighbour with the commits there that cite the lot and fall within the lot's period (`started` to `finished`) and, when the lot declares a `cite:` for that neighbour, contain that string (`aucun commit du lot`, or `introuvable` for a path that is not there) |
 | `raf now` | what to do next |
 | `raf list [--status s]` | flat list |
-| `raf docs-ok <lot> --reason text` | acknowledge the `docs.sync` gap of a lot (a document behind its commits, `raf check` red) when the documentation really stays true: a `docs_ok: { date, reason }` key on the lot, **the reason is required** (refused without it, for an unknown lot or for a sub-task); `raf check` and `cadence lead tour` no longer count the lot, `raf show` prints it, and `cadence orchestrate` neither calls the librarian nor holds the lot back for it. Commit the plan with it |
+| `raf docs-ok <lot> --reason text` | acknowledge the `docs.sync` gap of a lot (a document behind its commits, `raf check` red) when the documentation really stays true: a `docs_ok: { date, reason }` key on the lot, **the reason is required** (refused without it, for an unknown lot or for a sub-task); `raf check` and `cadence lead tour` no longer count the lot, `raf show` prints it, and `cadence orchestrate` neither calls the librarian nor holds the lot back for it. Commit the plan with it; on a read-only plan (kept by another tool) the key goes to `.cadence/docs-ok.yaml` instead, and that file is committed (L386) |
 | `raf ignore <sha> \| "exact subject" [--reason text]` | acknowledge a commit without a lot (tooling chore, a plan commit citing an unknown id) or a commit that cites known lots without working on them (a lead's plan commit creating lots, a setting cited in parentheses): it then counts for none of them — not started, not active, not to review (`raf commits` omits it) — without rewriting history: a dated, reasoned line in the plan's `acknowledged:` section; a sha is exact, a subject covers every commit carrying it; exactly one commit argument, the reason goes through `--reason "text"` (`raf ignore 1a2b3c4 "tooling"` is refused with « un seul commit attendu ; la raison se passe par --reason "texte" », exit 2) |
 | `raf check --ignored` | list the acknowledged commits with their date and reason |
 | `raf check [--since date] [--idle 7]` | since the plan's adoption date by default (a visible lot without a public title is only a `⚠` warning: it never changes the exit code): commits without a lot (commits touching only plan files, or only version fields, `CHANGELOG.md`, the README's « What's new » section and `docs/whats-new.md` are exempt), unknown ids, `todo` lots that already have commits, idle lots (an open lot whose sub-lots, entries carrying `parent:` in a plan kept by another tool, have a recent commit or are in progress is not idle: L321), `done` lots with open sub-tasks, bad or circular dependencies, and an open lot titled « Revue UX — <screen> » without `visible: true` (`ux-review-not-visible`, an error: such a lot goes through precheck → implement → review with no UX step, so the screen is never reviewed — finance L32 on 2026-10-23; L271; the message names the fix, `raf visible <id> on`, L273; on a read-only plan, plan kept by another tool, it never names a `raf` command, which would refuse: with `plan.fields.visible` mapped it says to set `visible:` with the project's tool, without it it says the plan carries no `visible`, to map the field in `cadence.yaml` (`plan.fields.visible`) if the project's tool writes it, and that otherwise the UX review of that screen happens outside orchestrate, L321) |
@@ -276,6 +276,10 @@ the file, and `raf now`, `raf list`, `raf commits`, `raf check`, `raf gantt` and
 `cadence session start|close` work on it. Such a plan is **read-only** —
 `raf add|start|done|note|ux|review` refuse and leave the file to the project's tool, and the two
 review gates do not apply to it (a `uxSince` or `reviewSince` written in it is ignored).
+One acknowledgement is kept outside the plan so it works here too: `raf docs-ok <lot> --reason "…"`
+writes `.cadence/docs-ok.yaml` (next to `cadence.yaml`, one line `L12: { date: 2026-10-27, reason: … }` per lot),
+never the plan; commit that file. `raf check`, `raf show`, `cadence lead tour` and `cadence orchestrate` read it
+(an entry without a reason acknowledges nothing, an unreadable file is an error that names it) (L386).
 
 ```yaml
 plan:

package/docs/whats-new.md

@@ -4,6 +4,7 @@
 
 ## In two lines
 
+- **1.17.0**: `cadence orchestrate` refuses a repository holding a `.git/index.lock`; `raf docs-ok` works on a plan kept by another tool; `cadence verify --gate` replays a red test alone, like the gate of a wave.
 - **1.16.1**: publishes 1.16.0 (tagged, never published), plus `raf gantt` counting commits without plan commits, one login check per `orchestrate --continue` launch, and a wider `CHANGELOG.md` conflict settled by worktree integration.
 - **1.16.0**: easier arrival for a team already equipped and for a new user: a `docs/with-your-tools.md` page, `raf --version`, no gap after `raf init`, Claude Code login checked before any write, commit counts without plan commits.
 - **1.15.1**: a getting-started page (`docs/quickstart.md`) takes a lead of several projects from install to the first wave and lists the usual stops; GitHub issue templates for bugs and requests; a contrast fix in the dark figure.
@@ -39,6 +40,8 @@ Each is a paragraph in [docs/whats-new.md](whats-new.md) and a full section in [
 
 The long form of « In two lines » above (the README no longer carries a « What's new » section since L326: it links here). The full history, with the date of each version, is in [CHANGELOG.md](../CHANGELOG.md).
 
+**1.17.0**: fewer stops that were not the lot's fault. `cadence orchestrate` and its `--dry-run` refuse a repository holding a `.git/index.lock` before writing anything (L385, `docs/orchestrate.md`): the message gives the age of the lock, whether a git process is running, and the `rm` command to remove a stale one. A plan commit that fails (stale lock, refusing hook) now puts the plan back as it was even when the lock blocks the index, where the next lot used to be handed back as a « dépôt sale ». `raf docs-ok` no longer refuses a plan kept by another tool (read-only): the acknowledgement of a `docs.sync` gap is written to `.cadence/docs-ok.yaml` (`L12: { date, reason }`, next to the project's `cadence.yaml`), the plan is never touched, and `raf check`, `raf show`, `cadence lead tour` and `cadence orchestrate` read it; the librarian's brief names that file to commit (L386). `cadence verify --gate` applies `orchestrate.testReplay` like the gate of a wave (L387, `docs/deliver.md`): a red test the output names is replayed alone, twice at most, and a test that passes alone is reported as unstable under load instead of turning the gate red. A red step that names no test prints the last 10 lines of its output, prefixed `  | `. The gate and the replay get `CADENCE_TEST_WORKERS` like a wave's gate (the caller's value, else cores ÷ `CADENCE_MAX_SESSIONS`), so `--maxWorkers=$CADENCE_TEST_WORKERS` works from a plain shell, and a red step says that a replay took place and how many tests it confirmed green.
+
 **1.16.1**: 1.16.0 was tagged but never published: a test added with it (R2 of L377) supposed `raf` installed in the `PATH`, found it on the developer's machine and not on the runner, and the publish run went red, a fault of the test and not of the tool (L384); 1.16.1 publishes it as it stands, so everything listed under 1.16.0 below arrives with it. The test suite no longer depends on a `raf` or a `cadence` installed on the machine (L384, `docs/releasing.md`): the test now has its hook run `raf` from the sources, and the suite removes every installed `raf` and `cadence` from the `PATH` of the tests (the other tools stay), so such a test is red on the lead's machine and in the gate, not only at publication. `raf gantt` counts the commits of a lot as `raf commits` does (L381, `docs/raf.md`): plan commits no longer inflate the commit column nor the tooltip of a bar, a lot whose only commit is `plan: L1 démarré` reads 0, and the filter reads the files of the commits in one `git log` call instead of one `git diff-tree` per commit (about 20 s down to 2 s on 2,700 commits for the Gantt page); a test now holds the same count for `cadence session start` and `close`, and the test that held `raf now` to the lots it shows can now fail. With `--continue`, `cadence orchestrate` reads `claude auth status` once per launch instead of again, up to 20 s each, for every candidate lot of every round (L382, `docs/orchestrate.md`), and the message quoted in `docs/quickstart.md` and `docs/orchestrate.md` no longer nests backticks inside backticks, which broke the Markdown rendering. The worktree integration of `cadence orchestrate` also settles a `CHANGELOG.md` conflict where one lot adds a section under `[Unreleased]` (`### Fixed`) with its entry and the other a bare entry (L383, `docs/orchestrate.md`): the bare entry is filed under the section the other side added, one section title and one entry per lot, instead of handing the lot back; with no single section to file it under, the conflict stays by hand.
 
 **1.16.0**: easier arrival, for a team that already has its tools and for someone who has never used cadence. A new page, `docs/with-your-tools.md` (L363, a short section of the README), is written for teams that already have a tracker, a `HANDOFF.md`, ADRs and a commit convention: what cadence does not replace, what is optional (`raf`, `session start|close`, the hook), what plugs into what you have (a plan kept by another tool, read-only, with your own ticket ids; `plan.commit` for the subject of the plan commits, which by default still read `plan: L12 démarré (orchestrate …)`, GitHub issue #15, L375; `docs.sync` for your docs) and what it adds (waves with an automatic review, a deliver that verifies the effect), with a figure. The other changes come from the walkthrough of a new user. `raf --version` and `raf -v` print the version, as `cadence --version` does, instead of `Unknown option '--version'` (L376, only as the first argument: `raf show --version` stays an unknown option), and `cadence orchestrate alpha:L1` launched from inside `alpha` says why the folder is not found (the project is a sub-folder of the current folder; inside a repository `.:L1` works). The commit that follows `raf init` no longer opens a « commit sans lot » gap (L377, `docs/raf.md`, `docs/quickstart.md`): what `raf init` writes and a `cadence.yaml` created in the same commit with only `plan:` and `orchestrate:` keys count as plan files, while a code file, another `.gitignore` line, a `deliver:` key or a later edit of `cadence.yaml` keeps it a gap, and the getting-started page drops its `raf ignore` workaround. `cadence orchestrate` checks that Claude Code is logged in (`claude auth status`) before starting a lot (L378, `docs/orchestrate.md`): when it is not, the command is refused before any write to the plan (no `raf start`, no commit, the lot stays `todo`) and the message says to run `claude` then `/login`, `--dry-run` reports it with a `⚠`; before, the lot was started and failed at the first session with `Not logged in`, left `doing`. `raf now`, `cadence lead tour` and `cadence session start` count the commits of a lot as `raf commits` does (L379, `docs/raf.md`, `docs/lead.md`, `docs/session.md`): plan commits, which touch only plan files, are left out, so a lot just started reads `0 commit` instead of `1 commit(s)` while `raf commits` lists nothing, and the period journals of `session start` and `session close` leave them out too. `cadence release` prints `cadence verify --gate --sha HEAD` right after the version commit, before the plugin evaluation and the tag, so the suite runs on the commit that will be published (L380, `docs/releasing.md`), and the tests that look for the entry of a lot in `CHANGELOG.md` read the section that carries it, not `[Unreleased]` alone, which the version commit empties, a fault that had stopped the release of 1.14.0 and again the next one (a guard test refuses the pattern).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sylad/cadence",
-  "version": "1.16.1",
+  "version": "1.17.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",