@sylad/cadence 1.8.0 → 1.9.0

package/dist/resources.js

@@ -0,0 +1,51 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { parse } from 'yaml';
+import { isOpen, RafError, RESOURCE_NAME, RESOURCES_BAD_LIST } from './plan.js';
+/**
+ * Clé `resources:` du cadence.yaml le plus proche en remontant depuis le dossier parent de `root` : le premier fichier qui porte la clé
+ * (même vide) l'emporte. Aucun ne la porte : liste vide, attribuée au cadence.yaml du parent direct. Un fichier illisible ou une clé
+ * qui n'est pas une liste de noms valides est une `RafError` nommant le fichier, jamais une liste vide silencieuse.
+ */
+export function readResources(root) {
+    const fallback = join(dirname(root), 'cadence.yaml');
+    for (let dir = dirname(root);; dir = dirname(dir)) {
+        const file = join(dir, 'cadence.yaml');
+        if (existsSync(file) && statSync(file).isFile()) {
+            let raw;
+            try {
+                raw = parse(readFileSync(file, 'utf8'));
+            }
+            catch (e) {
+                throw new RafError(`${file} illisible : ${e.message.split('\n')[0]}`);
+            }
+            if (raw != null && typeof raw === 'object' && Object.hasOwn(raw, 'resources')) {
+                const list = raw.resources ?? [];
+                if (!Array.isArray(list) || !list.every((n) => typeof n === 'string' && RESOURCE_NAME.test(n)))
+                    throw new RafError(`${file} : resources ${RESOURCES_BAD_LIST}`);
+                return { file, names: [...new Set(list)] };
+            }
+        }
+        if (dirname(dir) === dir)
+            return { file: fallback, names: [] };
+    }
+}
+/**
+ * Un écart par ressource d'un lot ouvert que le cadence.yaml des dossiers parents ne déclare pas. Le fichier n'est lu que si un lot ouvert
+ * porte `uses:` : un plan qui n'en porte pas donne le contrôle d'avant, quel que soit l'état du dossier parent.
+ */
+export function resourceIssues(lots, root) {
+    const using = lots.filter((l) => isOpen(l.status) && l.uses?.length);
+    if (using.length === 0)
+        return [];
+    let declared;
+    try {
+        declared = readResources(root);
+    }
+    catch (e) {
+        if (e instanceof RafError)
+            return [{ message: e.message }];
+        throw e;
+    }
+    return using.flatMap((l) => l.uses.filter((n) => !declared.names.includes(n)).map((n) => ({ message: `${l.id} utilise la ressource « ${n} », non déclarée dans ${declared.file} (resources:)` })));
+}

package/dist/session.js

@@ -81,6 +81,8 @@ export function lastActivity(lot, commits) {
     const days = [commits[0]?.day, lot.started, ...lot.notes.map((n) => n.date)].filter((d) => !!d);
     return days.length ? days.reduce(maxDay) : undefined;
 }
+/** « 0 commit », « 1 commit », « 3 commits » : le zéro se dit, une note de clôture sur un lot sans commit ne se lit pas comme « fini ». */
+export const commitCount = (n) => `${n} commit${n > 1 ? 's' : ''}`;
 const hhmm = (d) => `${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}`;
 /**
  * Fenêtre de la clôture : --since s'il est donné ; sinon depuis la dernière ouverture du
@@ -114,10 +116,11 @@ export function sessionStart(ctx, opts) {
     if (doing.length === 0)
         out('  (rien)');
     for (const l of doing) {
-        const last = lastActivity(l, all.byLot.get(l.id) ?? []);
+        const commits = all.byLot.get(l.id) ?? [];
+        const last = lastActivity(l, commits);
         const idle = last ? diffDays(last, today) : 0;
         const state = last ? `dernière activité ${last}${idle > opts.idle ? `, silencieux depuis ${idle} j` : ''}` : 'aucune activité';
-        out(`  ${l.id}  ${l.title}  (${state})`);
+        out(`  ${l.id}  ${l.title}  (${commitCount(commits.length)}, ${state})`);
     }
     section(out, 'En attente', gateWaiting(lots, blocked).map(({ lot, text }) => `${lot.id}  ${lot.title}  (${text})`));
     const recent = period(ctx, opts.since);

package/dist/state.js

@@ -156,9 +156,48 @@ export function pidAlive(pid) {
 export function appendDelivery(dir, day, sha) {
     appendFileSync(join(dir, 'deliveries.log'), `${day} ${sha}\n`);
 }
-/** Ajoute une livraison rouge (« jour sha raison ») à `deliveries-failed.log` ; la raison est la première ligne du message d'échec. */
-export function appendFailedDelivery(dir, day, sha, reason) {
-    appendFileSync(join(dir, 'deliveries-failed.log'), `${day} ${sha} ${reason.split('\n')[0].trim()}\n`);
+/** Classe d'une livraison rouge : où elle a cassé. `refus` : le script a refusé avant d'agir (code 2). */
+export const FAIL_CLASSES = ['refus', 'ci', 'deploiement', 'verification'];
+const TAIL_SEP = ' ⏎ ';
+const TAIL_LINES = 5;
+const LINE_MAX = 200;
+const REASON_MAX = 300;
+// eslint-disable-next-line no-control-regex
+const ANSI = /\u001b\[[0-9;?]*[ -/]*[@-~]/g;
+// eslint-disable-next-line no-control-regex
+const CONTROL = /[\u0000-\u001f\u007f]/g;
+const MASK = '***';
+const SECRET_WORDS = new Set(['token', 'secret', 'password', 'passwd', 'pwd', 'pass', 'key', 'credential', 'credentials', 'auth', 'authorization', 'signature', 'sig', 'jwt', 'cookie']);
+// Mots sensibles qui, collés à un autre (APIKEY, ACCESSTOKEN, GITHUBTOKEN), terminent encore un nom : pas « pass », « sig » ou « auth » (BYPASS, ...).
+const SECRET_SUFFIXES = ['token', 'secret', 'password', 'passwd', 'key', 'credential', 'credentials', 'signature', 'pwd'];
+// Un nom de variable ou de paramètre d'URL est sensible quand l'un de ses mots (séparés par _ - . ou une majuscule) en est un, ou finit par l'un des suffixes.
+const sensitiveName = (name) => name
+    .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+    .split(/[_.-]/)
+    .some((w) => SECRET_WORDS.has(w.toLowerCase()) || SECRET_SUFFIXES.some((x) => w.toLowerCase().endsWith(x)));
+const TOKEN_SHAPES = /\b(?:gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|glpat-[A-Za-z0-9_-]{16,}|sk-[A-Za-z0-9_-]{16,}|xox[abprs]-[A-Za-z0-9-]{10,}|AKIA[0-9A-Z]{16}|npm_[A-Za-z0-9]{30,})\b/g;
+const BEARER = /\b(Bearer|Basic)\s+[A-Za-z0-9._~+/=-]{8,}/gi;
+const URL_USERINFO = /(\b[a-z][a-z0-9+.-]*:\/\/)[^\s/@]+@/gi;
+const ASSIGNMENT = /([A-Za-z][A-Za-z0-9_.-]*)=("[^"]*"|'[^']*'|[^\s&"']+)/g;
+/** Masque ce qui ressemble à un secret (jeton connu, Bearer, identifiants d'URL, VAR=valeur ou paramètre d'URL au nom sensible) : motifs probables, pas une garantie. */
+export const maskSecrets = (line) => line
+    .replace(BEARER, `$1 ${MASK}`)
+    .replace(URL_USERINFO, `$1${MASK}@`)
+    .replace(TOKEN_SHAPES, MASK)
+    .replace(ASSIGNMENT, (m, name) => (sensitiveName(name) ? `${name}=${MASK}` : m));
+const clean = (line, max) => {
+    const t = maskSecrets(line.replace(ANSI, '').replace(CONTROL, ' ')).replaceAll('⏎', ' ').trim();
+    return t.length > max ? `${t.slice(0, max - 1)}…` : t;
+};
+/**
+ * Ajoute une livraison rouge à `deliveries-failed.log` : une ligne « jour sha [classe] raison ⏎ ligne ⏎ ligne ».
+ * La raison est la première ligne du message d'échec ; `tail` (sortie de la commande en échec) est borné à ses
+ * 5 dernières lignes non vides de 200 caractères, sans séquence ANSI, secrets probables masqués (raison comprise).
+ */
+export function appendFailedDelivery(dir, day, sha, reason, cls, tail = []) {
+    const kept = tail.flatMap((l) => clean(l, LINE_MAX) || []).slice(-TAIL_LINES);
+    const head = `${day} ${sha} ${cls ? `[${cls}] ` : ''}${clean(reason.split('\n')[0], REASON_MAX)}`;
+    appendFileSync(join(dir, 'deliveries-failed.log'), `${[head, ...kept].join(TAIL_SEP)}\n`);
 }
 export function lastDelivery(dir) {
     const file = join(dir, 'deliveries.log');
@@ -179,15 +218,29 @@ export function readDeliveries(dir) {
         return null;
     }
 }
-/** Les jours de `deliveries-failed.log` (une ligne « jour sha raison » par livraison rouge), dans l'ordre du fichier ; une ligne illisible est ignorée, un fichier absent ou illisible donne aucune livraison rouge. Lecture seule : ne crée rien. */
-export function readFailedDeliveries(dir) {
+/** Les livraisons rouges de `deliveries-failed.log`, dans l'ordre du fichier ; une ligne illisible est ignorée, un fichier absent ou illisible donne aucune livraison rouge. Lecture seule : ne crée rien. */
+export function readFailedEntries(dir) {
     try {
         return readFileSync(join(dir, 'deliveries-failed.log'), 'utf8')
             .split('\n')
-            .map((l) => l.split(' ')[0])
-            .filter(isDay);
+            .flatMap((line) => {
+            const [head = '', ...tail] = line.split(TAIL_SEP);
+            const m = /^(\S+)(?: (\S+))?(?: (.*))?$/.exec(head);
+            if (!m || !isDay(m[1]))
+                return [];
+            let reason = m[3] ?? '';
+            const c = /^\[(\w+)\] ?/.exec(reason);
+            const cls = c && FAIL_CLASSES.includes(c[1]) ? c[1] : null;
+            if (cls)
+                reason = reason.slice(c[0].length);
+            return [{ day: m[1], sha: m[2] ?? '', cls, reason, tail }];
+        });
     }
     catch {
         return [];
     }
 }
+/** Les jours de `deliveries-failed.log` (une ligne par livraison rouge), dans l'ordre du fichier. */
+export function readFailedDeliveries(dir) {
+    return readFailedEntries(dir).map((e) => e.day);
+}

package/dist/testgate.js

@@ -0,0 +1,15 @@
+import { docSyncSet } from './docsync.js';
+export const DEFAULT_TEST_PATTERNS = ['**/*.test.*', '**/*.spec.*', 'test/**', 'tests/**', '**/__tests__/**'];
+/**
+ * Les fichiers de code que le lot a modifiés sans toucher le moindre fichier de test (triés), ou rien : un test touché, ou
+ * moins de `threshold` fichiers de code. Un fichier de test n'est jamais du code, même quand il correspond à `code`.
+ */
+export function testGateMissing(gate, files) {
+    const isTest = docSyncSet(gate.tests);
+    if ([...files].some(isTest))
+        return [];
+    const isCode = docSyncSet(gate.code);
+    const isException = gate.except.length ? docSyncSet(gate.except) : () => false;
+    const code = [...files].filter((f) => isCode(f) && !isException(f)).sort();
+    return code.length >= gate.threshold ? code : [];
+}

package/docs/cadence-hud.md

@@ -27,6 +27,18 @@ ol      ▮▮▮▮▮▯▯▯▯▯ 39/78 · 0 en cours · +3 cette semaine
 cadence ▮▮▮▮▮▯▯▯▯▯ 10/20 · 2 en cours : L149 L153
 ```
 
+The **sessions of the lead** (L276) — the ones started by hand and declared with `cadence lead hold <label>` — are drawn
+under the waves, even when no wave is running: the slots line of `cadence orchestrate --status` and one line per session
+(label, age, time left):
+
+```
+sessions du lead : 1 · créneaux libres : 2 sur 3
+  correctif-L12  depuis 4 min · reste 56 min
+```
+
+With a live wave and no held session the line reads `créneaux libres : 1 sur 2`; with neither, nothing. A session whose
+time limit has run out stops counting in the slots but is not dropped (L278): a row `⚠ session du lead échue : correctif-B28  échue depuis 2 h 10` stays under the others (in red) until `cadence lead release <label>` or a renewed `lead hold`, since nothing stops the session itself. They are read from disk (`holds/` of the cadence home), like the waves.
+
 The bar is lots done over lots done + in progress + to do (dropped and recurring lots left out); the count of lots in progress is followed by their ids (`2 en cours : L149 L153`), cut to three then `…` (`5 en cours : L1 L2 L3 …`), the count alone at zero;
 `+N cette semaine` counts the lots created in the last 7 days (today and the six before) and is left out at zero. The source is
 `cadence lead tour <folder> --json` (the folder a wave was launched from, otherwise the session's: a folder of projects gives one line per project, a project with no sub-project gives its own single line),

package/docs/cycle-vague-dark.svg

@@ -38,5 +38,5 @@
 <line x1="981" y1="127" x2="981" y2="68" stroke="#58a6ff" stroke-width="1.2" stroke-dasharray="3 3" marker-end="url(#a)"/>
 <text x="73" y="216" font-size="11.5" fill="#8b949e">dashed: only for a lot with a page or a behaviour to pin down (screen: page, spec: true)</text>
 <text x="661" y="216" font-size="11.5" fill="#8b949e">each step in a fresh session, driven by cadence orchestrate</text>
-<text x="20" y="236" font-size="11.5" fill="#8b949e">Every verdict is written to the plan (docs/plan/raf.yaml); a delivery counts only when its checks pass.</text>
+<text x="20" y="236" font-size="11.5" fill="#8b949e">Every verdict is written to the plan (.cadence/raf.yaml); a delivery counts only when its checks pass.</text>
 </svg>

package/docs/cycle-vague-light.svg

@@ -38,5 +38,5 @@
 <line x1="981" y1="127" x2="981" y2="68" stroke="#0969da" stroke-width="1.2" stroke-dasharray="3 3" marker-end="url(#a)"/>
 <text x="73" y="216" font-size="11.5" fill="#57606a">dashed: only for a lot with a page or a behaviour to pin down (screen: page, spec: true)</text>
 <text x="661" y="216" font-size="11.5" fill="#57606a">each step in a fresh session, driven by cadence orchestrate</text>
-<text x="20" y="236" font-size="11.5" fill="#57606a">Every verdict is written to the plan (docs/plan/raf.yaml); a delivery counts only when its checks pass.</text>
+<text x="20" y="236" font-size="11.5" fill="#57606a">Every verdict is written to the plan (.cadence/raf.yaml); a delivery counts only when its checks pass.</text>
 </svg>

package/docs/deliver.md

@@ -43,6 +43,33 @@ cadence deliver              # 0 delivered and verified · 1 a step failed · 2
   CI can only build what was pushed); no other delivery running (a lock whose
   process died is removed with a warning); with `ci: github`, `gh` installed and
   logged in.
+- **Red delivery log** (L282): a failure after the lock is taken appends one line to
+  `<git common dir>/cadence/deliveries-failed.log`: `day sha [class] reason ⏎ line ⏎ line`.
+  The class says where it broke: `refus` (the project script exited with code 2 — the
+  convention of `deliver` itself for « refused before acting »), `ci`, `deploiement`
+  (the project script with any other code, a deploy command, an unusable
+  `CADENCE_DEPLOYED_FILE`) or `verification`. The reason is the first line of the failure
+  message, followed by the **last 5 non-empty lines** (200 characters each, ANSI sequences
+  removed) of the output of the command that failed: the project script, the CI command, the
+  deploy command or the check command. A GitHub CI run or an URL check has no output of its
+  own, so no line follows. cadence now relays the output of those commands through itself
+  (same bytes on its own stdout and stderr, but the command no longer sees a terminal there,
+  so it may drop colours or progress bars). A line rewritten with `\r` (a progress bar that
+  did not drop) keeps only its last non-empty frame, not 5 frames of the bar. **Probable
+  secrets are masked** (`***`) in the reason and in those lines before the file is written:
+  known token shapes (GitHub, GitLab, npm, Slack, AWS key id, `sk-…`), `Bearer`/`Basic`
+  values, `user:password@` in a URL, and any `NAME=value` (shell variable or URL query
+  parameter) whose name has a word such as token, secret, password, key, auth, signature, or
+  ends with one of token, secret, password, pwd, key, credential, signature (`APIKEY`,
+  `ACCESSTOKEN`, `GITHUBTOKEN`, `MYSQLPWD`) (L294). The 8192 characters kept are the END of the
+  output (`OUTPUT_KEPT`, `src/deliver.ts`), so the bound cannot cut the end of a value; it can cut
+  its beginning (the name and the opening quote gone), and that case is **not handled** — the log
+  stays local. A quoted value never closed is not treated either (L294 tried, and each fix opened a
+  new leak): only closed values and unquoted values are matched.
+  This is a list of likely patterns, not a guarantee: a secret of another shape printed by a
+  command can still land in the log, which stays local (`<git common dir>/cadence/`). `cadence perf` reads classes and projects from it
+  ([perf](perf.md#delivery-quality-and-the-tour-header-l227)); a line written before L282
+  has no class and counts as « non classée ».
 - Every command is killed when it exceeds its budget (CI, `deployTimeout`, what is
   left of `verifyTimeout`) and reported as "délai dépassé". Killed means the
   whole tree, followed while the command runs: every 200 ms cadence lists the
@@ -90,7 +117,7 @@ cadence deliver              # 0 delivered and verified · 1 a step failed · 2
   5 minutes is a failure (you probably pushed another commit than the one you
   deliver); every run must end `success`, `skipped` or `neutral`. `gh` errors
   are retried, and reported with their cause after 5 minutes.
-- Commands get `CADENCE_SHA`, `CADENCE_SHORT` (7 characters) and `CADENCE_BRANCH`;
+- Commands get `CADENCE_SHA`, `CADENCE_SHORT` (7 characters) and `CADENCE_BRANCH` (a `deliver.script` also gets `CADENCE_DEPLOYED_FILE`, see below);
   `${SHA}` and `${SHORT}` are replaced in `url` and `contains`.
 - On success the lots cited by the commits since the previous delivery are
   listed, so you can `raf done` those whose effect you have seen. With a
@@ -124,13 +151,41 @@ cadence deliver --sha 6b0d9aa -- api                                  # an earli
 `--sha` (any mode) delivers a pushed commit other than `HEAD` — for a CI that
 builds each service only on the commit that touched it. `allowDirty` suits a
 working tree shared by several sessions when the delivery starts from a pushed
-sha and never from local files; without it a modified tree is refused.
+sha and never from local files; without it a modified tree is refused. `--sha`
+itself never reads the working tree: a tracked file modified outside the delivered
+sha (the plan after `raf done`, say) neither refuses nor is reported, with or
+without `allowDirty`.
+
+**While a wave runs.** `cadence orchestrate` holds the repository: a plain `cadence deliver` is refused until every lot of the
+repository in the wave is ready or handed back. `--sha` is the exception (L277): it is accepted while the wave runs when no
+commit in the history of `<sha>` belongs to a lot of the wave that is not ready (running, queued, in question, suspended,
+handed back, failed), that is when `<sha>` is « livrable jusqu'à » (the line the wave's final table prints). A ready lot is
+then delivered while the wave runs, without waiting for the slowest lot. The refusal names the lots that hold the sha back. A lot's commits
+are what git attributes to it in the repository (the commits that cite it) **and** what its sessions' reports noted, for the project's own
+repository as for a neighbour one (the lot's `repos:` key): git sees at once the commit of a session still running, cut by the quota or failed,
+which the reports only note when the session ends validly. A lot of the wave with no commit yet blocks nothing. What cannot be verified is
+refused: an unreadable wave state, an unknown sha, or a lot that is not ready whose commits cannot be read (its project's plan is unreadable or
+does not know the lot) while none of the commits already known holds the sha back. Push the sha alone first (`git push origin <sha>:main`).
+
+**What is logged as delivered.** cadence no longer guesses which commit a project script deployed. Before running `deliver.script` it creates an
+empty file and hands its path to the script in `CADENCE_DEPLOYED_FILE` (next to `CADENCE_SHA`, `CADENCE_SHORT`, `CADENCE_BRANCH`). A script
+that deploys a commit other than `CADENCE_SHA` (it committed a `--news` timestamp itself, say) writes that sha into the file. After the script:
+
+- the file holds a hexadecimal sha (7 to 40 characters) that resolves to a commit: that is the sha logged, and `✓ livré :` names it (« sha déclaré par le script ») — it wins over
+  HEAD, during a wave or not;
+- the file holds anything else (not a commit, several lines, `HEAD` or a branch name — a revision would be resolved after the script, possibly at another lot's commit, so only a sha is accepted): the delivery fails with a message that says so, nothing is logged;
+- the file is empty and the delivery runs **while a wave runs**: the log keeps `<sha>`, and if HEAD moved during the delivery a warning says
+  so (« la tête a avancé pendant la livraison ; sans sha déclaré par le script (CADENCE_DEPLOYED_FILE), le journal garde <sha> ») — the new
+  commit may be the script's, a running lot's, or a plan commit, and cadence cannot tell them apart;
+- the file is empty and **no wave runs**: the historical rule stays, a script that committed and pushed during the delivery has delivered the new
+  HEAD, which is logged (« head moved by the script »).
 
 cadence keeps what the script usually lacks: the preconditions (clean tree, pushed
 `HEAD`), the lock (never two deliveries at once), the delivery log and the lots
 delivered. Arguments are quoted for `sh`, so spaces and quotes reach the script
 intact. If the script commits and pushes during the delivery (stamping a
-changelog entry, say), the new `HEAD` is the sha recorded as delivered. Exit code
+changelog entry, say), outside a wave the new `HEAD` is the sha recorded as delivered; during a wave, or to be exact
+about it anywhere, the script declares it in `CADENCE_DEPLOYED_FILE` (above). Exit code
 0 of the script means delivered; `verify` checks, if any, run after it.
 
 ## verify: replay the effect checks, outside a delivery

package/docs/fonctionnement-wave-dark.svg

@@ -1,6 +1,6 @@
 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1320 350" width="1320" height="350" role="img" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif" font-size="13" fill="#e6edf3">
 <title>A lot inside an orchestrate wave</title>
-<desc>A lot without commits starts with a precheck (unless orchestrate.precheck is false), then by type through spec, mockup or sheet review and sealed acceptance tests, or straight to the implementation; then the code review, corrections (two passes, a third if the review converges), the UX pass if visible, once, after the compliant code review, and an automatic raf review.</desc>
+<desc>A lot without commits whose title cites a finding or an earlier lot starts with a precheck (unless orchestrate.precheck is false), then by type through spec, mockup or sheet review and sealed acceptance tests, or straight to the implementation; then the code review, corrections (two passes, a third if the review converges), the UX pass if visible, once, after the compliant code review, and an automatic raf review.</desc>
 <defs><marker id="arr2" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 z" fill="#8b949e"/></marker></defs>
 <rect width="1320" height="350" fill="#0d1117"/>
 <rect x="20" y="140" width="120" height="52" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5" stroke-dasharray="6 4"/>

package/docs/fonctionnement-wave-light.svg

@@ -1,6 +1,6 @@
 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1320 350" width="1320" height="350" role="img" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif" font-size="13" fill="#1f2328">
 <title>A lot inside an orchestrate wave</title>
-<desc>A lot without commits starts with a precheck (unless orchestrate.precheck is false), then by type through spec, mockup or sheet review and sealed acceptance tests, or straight to the implementation; then the code review, corrections (two passes, a third if the review converges), the UX pass if visible, once, after the compliant code review, and an automatic raf review.</desc>
+<desc>A lot without commits whose title cites a finding or an earlier lot starts with a precheck (unless orchestrate.precheck is false), then by type through spec, mockup or sheet review and sealed acceptance tests, or straight to the implementation; then the code review, corrections (two passes, a third if the review converges), the UX pass if visible, once, after the compliant code review, and an automatic raf review.</desc>
 <defs><marker id="arr2" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 z" fill="#57606a"/></marker></defs>
 <rect width="1320" height="350" fill="#ffffff"/>
 <rect x="20" y="140" width="120" height="52" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5" stroke-dasharray="6 4"/>

package/docs/fonctionnement.md

@@ -12,7 +12,7 @@ box with a blue outline is where the work is kept or checked.
   <img alt="A lot goes from todo to doing, receives commits that cite it, gets its review and UX verdicts, becomes done, then is delivered by cadence deliver" src="fonctionnement-lot-light.svg">
 </picture>
 
-The plan (`docs/plan/raf.yaml`, or the file `cadence.yaml` names) is the single source of truth:
+The plan (`.cadence/raf.yaml`, the legacy `docs/plan/raf.yaml`, or the file `cadence.yaml` names) is the single source of truth:
 `raf check` reports every commit that cites no lot (unless a motivated `raf ignore` covers it).
 `hook.autostart` in `cadence.yaml` sets what the pre-commit hook does with a commit that cites a lot
 still `todo`: `warn` (the default), `refuse`, or `start` it in the same commit. `raf done` is refused
@@ -22,10 +22,10 @@ while a sub-task is open. A delivery is finished only when its effect checks pas
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="fonctionnement-wave-dark.svg">
-  <img alt="A lot without commits starts with a precheck (unless disabled), then by type through spec, mockup or sheet review and sealed acceptance tests, or straight to the implementation; then the UX pass if visible, the code review, corrections and an automatic raf review" src="fonctionnement-wave-light.svg">
+  <img alt="A lot without commits whose title cites a finding or another lot starts with a precheck (unless disabled), then by type through spec, mockup or sheet review and sealed acceptance tests, or straight to the implementation; then the UX pass if visible, the code review, corrections and an automatic raf review" src="fonctionnement-wave-light.svg">
 </picture>
 
-A lot without commits yet starts with the **precheck** (unless `orchestrate.precheck: false`; a lot that already has commits is never pre-checked): is the deliverable already there? « Yes » hands the lot back
+A lot without commits yet whose title cites a finding (`constat`, `revue`, `review`, `audit`) or another lot (its `goal:` counts like its title) starts with the **precheck** (unless `orchestrate.precheck: false`; a lot that already has commits, or whose title (or `goal:`) cites neither, is never pre-checked — L288): is the deliverable already there? « Yes » hands the lot back
 to the lead; « partial » passes what exists to the implementation. Then:
 
 - `screen: page` only: **spec** (mockup and screen sheet), **mockup review** (`ux-reviewer`, two
@@ -81,7 +81,7 @@ The budget a wave gives a lot is derived from its estimate, measured on the runs
 
 | Lot | Budget |
 |---|---|
-| up to 0.5 day | 540 k tokens |
+| up to 0.5 day | 600 k tokens |
 | 0.5 to 1 day | 750 k |
 | beyond | 570 k per day, 750 k at least |
 | `screen: page` | 1.3 M at least, or the ordinary budget + 450 k if that is more |
@@ -96,7 +96,7 @@ The final review is always played; the budget bounds the writing passes. A `scre
 
 - **Session cap.** As many sessions or subagents running at once as the cap (2 by default, set by the
   human with `CADENCE_MAX_SESSIONS` or `--max-sessions`). The lead never raises it itself.
-- Never two sessions in the same repository at the same time.
+- Never two sessions in the same repository at the same time. (An experimental worktree mode, `orchestrate.worktrees: true`, would let two independent lots of one repository play at once; it is refused without `CADENCE_EXPERIMENTAL_WORKTREES=1`, lots L299–L301 to do before it is enabled — [docs/orchestrate.md](orchestrate.md#one-worktree-per-lot-orchestrateworktrees-l279).)
 - A session cannot ask the human anything: it stops and reports, and the lead brings the question back.
 - A sealed acceptance test that contradicts its sheet is corrected by the lead with
   `cadence spec reseal <lot> <test> --reason "…"`, never by editing `acceptation.json`.

package/docs/lead.md

@@ -10,7 +10,7 @@ summaries, decides with the human, and leaves the work to fresh short sessions r
   <img alt="The lead workflow in three lanes (human, lead session, orchestrate program and agents), from the tour of the projects to the close of the session" src="lead-workflow-light.svg">
 </picture>
 
-Dashed boxes are conditional steps: the precheck runs only for a lot without a commit yet (unless `orchestrate.precheck: false`), and the spec, sheet review and accept steps run only for a `screen: page` lot or a `spec: true` lot. The skill itself is `skills/lead/SKILL.md`; this page is its
+Dashed boxes are conditional steps: the precheck runs only for a lot without a commit yet whose title cites a finding (`constat`, `revue`, `review`, `audit`) or another lot (unless `orchestrate.precheck: false`), and the spec, sheet review and accept steps run only for a `screen: page` lot or a `spec: true` lot. The skill itself is `skills/lead/SKILL.md`; this page is its
 picture, not its source.
 
 ## The steps
@@ -20,9 +20,10 @@ picture, not its source.
    quick wins. It stops and waits: the human picks the lots and the order (`--priority`, or the
    `priority:` list of the parent folder's `cadence.yaml`).
 2. **Wave.** The lead starts `cadence orchestrate <project>:<lot> … --wave <id>` in the background.
+   When a lot's title is stale, the lead does not delegate by hand: it passes `--goal "…"` (one lot per launch), or writes a `goal:` key on the lots in the plan (several lots at once) — in the native plan as `goal:`, in a plan kept by another tool (read-only) by mapping its key with `plan.fields: { goal: <their key> }` in `cadence.yaml` — which replaces the title as the objective of the briefs (L258, [orchestrate](orchestrate.md)).
    For each lot the program runs, in fresh sessions and in this order: `precheck → spec → maquette →
-   accept → implement → review → ux`. The **precheck** applies to any lot without a commit yet (unless
-   `orchestrate.precheck: false`). The spec steps exist only for a lot that declares
+   accept → implement → review → ux`. The **precheck** applies to a lot without a commit yet whose title cites a finding (`constat`, `revue`, `review`, `audit`) or another lot (unless
+   `orchestrate.precheck: false`; L288). The spec steps exist only for a lot that declares
    a `screen:` of `page` (a visible lot that creates or changes a whole screen; `screen: component` and `screen: journey`
    lots take the ordinary path, straight to the implementation, unless they already have a sheet) or `spec: true` (a lot without a screen
    that still has a behaviour to pin down: `precheck → spec → fiche → accept → implement → review`);
@@ -62,7 +63,7 @@ picture, not its source.
    UX reviewer's captures: the lead records `raf ux` on the human's verdict, never on its own — unless the parent folder's `cadence.yaml` says `lead.ux: lead`: then the lead forms the verdict from the reviewer's report and its own look at the captures, and asks the human only at the slightest doubt. Then
    `raf done`.
 6. **Delivery.** Push (for a « livrable jusqu'à <sha> », that sha alone, never HEAD), then
-   `cadence deliver`. After a green delivery that changes what a page shows or what it is served, the
+   `cadence deliver`. A lot that turns ready is delivered while the wave runs (`cadence deliver --sha <sha>`, accepted when no commit of the sha belongs to a lot that is not ready), not at the end of the wave. After a green delivery that changes what a page shows or what it is served, the
    `qa-reviewer` agent walks the delivered pages in a real browser, reads only, and brings its blocking
    findings to the human. It is not a gate: a finding becomes a new lot.
 7. **Threshold and chaining.** Before every new wave the lead reads `cadence session context`. Under
@@ -79,9 +80,9 @@ picture, not its source.
 
 | Rule | Why |
 |---|---|
-| At most **as many subagents as the session cap** running at once (2 by default; the human sets it with `CADENCE_MAX_SESSIONS`), orchestrate sessions included | `cadence orchestrate --status` and `cadence lead tour` print `créneaux libres : N sur M`, M being the configured cap; the lead never raises `--max-sessions` or `CADENCE_MAX_SESSIONS` itself |
-| Never two sessions in the same repository at the same time; the lead does not commit where a wave runs | a wave's lock refuses `cadence deliver` while a lot still works there |
-| A locked acceptance test that contradicts the sheet is corrected by the lead with `cadence spec reseal <lot> <test> --reason "…"` (lot in progress, outside a wave; an amended sheet is accepted once committed, every commit that touched it citing the lot, L217, never put it back to the red state; a delivered lot with an unstable test: add `--porteur <lot in progress>`, L212), then `--resume --answer` for a lot in question, or a new `cadence orchestrate <project>:<lot>` for a lot handed back (`--resume` skips it) | never by a session, never by editing `acceptation.json` |
+| At most **as many subagents as the session cap** running at once (2 by default; the human sets it with `CADENCE_MAX_SESSIONS`), orchestrate sessions included | `cadence orchestrate --status` and `cadence lead tour` print `créneaux libres : N sur M`, M being the configured cap and the sessions the lead started by hand (`cadence lead hold`, L255) being subtracted; the lead never raises `--max-sessions` or `CADENCE_MAX_SESSIONS` itself |
+| Never two sessions in the same repository at the same time; the lead does not commit where a wave runs (the experimental worktree mode, `orchestrate.worktrees: true`, is refused without `CADENCE_EXPERIMENTAL_WORKTREES=1` until L299–L301 are done: not a rule for the lead) | a wave's lock refuses `cadence deliver` while a lot still works there |
+| A locked acceptance test that contradicts the sheet is corrected by the lead with `cadence spec reseal <lot> <test> --reason "…"` (lot in progress, outside a wave and with no wave that is not `done` keeping open a lot of the repository still `doing` in its plan, the resealed lot or another, e.g. a question waiting: `--resume --answer` or `--drop` first, the one error lists every wave concerned, the live one that holds the lock (to wait for) and the stopped ones, and gives for each stopped wave the single `cd <launch folder> && cadence orchestrate --resume <wave> --drop <project>:<lot> [--drop …]` to run, a `--drop` per open lot of the repository in that wave, the queued ones that are not `doing` in the plan included, since `--resume` would relaunch them and they would take the lock back, L238 L239; an amended sheet is accepted once committed, every commit that touched it citing the lot, L217, never put it back to the red state; a delivered lot with an unstable test: add `--porteur <lot in progress>`, L212), then a new `cadence orchestrate <project>:<lot>` for a lot handed back (`--resume` skips it) | never by a session, never by editing `acceptation.json` |
 | Deliveries and the `raf ux` / `raf review` verdicts belong to the lead, one project at a time | never to a subagent, never two deliveries in parallel |
 | The UX verdict is the human's unless `lead.ux: lead` (parent `cadence.yaml`, default `human`) | then the lead decides from the report and the captures, and brings any doubt to the human |
 | A session cannot ask the human anything | it stops and reports; the lead brings the question back |
@@ -107,33 +108,55 @@ The mechanics around it (the life of a lot in the plan, a lot inside a wave, put
 [fonctionnement.md](fonctionnement.md). See also the [lead tour](lead.md#lead-tour) section below and the [orchestrate](orchestrate.md#orchestrate)
 page.
 
+## lead hold and release
+
+`cadence lead hold <label> [--ttl minutes]` and `cadence lead release <label>` (L255) declare the sessions the lead starts by hand — a fix subagent, a review, a QA pass launched outside an orchestrated wave. No wave carries such a session, so the slot registry could not see it: on 2026-10-23 the lead ran 4 sessions under a cap of 3 while `créneaux libres` said one slot was free. `hold` registers the session under its label for `--ttl` minutes (an integer ≥ 1, 60 by default; holding the same label again renews it instead of counting twice); `release` hands it back (releasing a label that is not held answers `aucune session « <label> » inscrite` and exits 0). A hold whose time has run out stops counting, but is not forgotten: nothing stops the session (L278), so `cadence lead tour` and `cadence orchestrate --status` print `⚠ session du lead échue : <label> (inscrite depuis 5 h 10 min, échue depuis 2 h 10 min) — la reprendre (cadence lead hold <label> --ttl <minutes>) ou l'arrêter (cadence lead release <label>)` after the slots line, and the `cadence-hud` band shows the same ⚠ row, until the lead renews the hold or releases it (an expired hold nobody touched is dropped 24 h after its expiry). The `--ttl` is therefore the maximum duration declared for the session; the `lead` skill says to renew or stop it at each ⚠. The line is not part of `--json`.
+
+The held sessions are kept in the `holds/` folder of the cadence home (`CADENCE_HOME`, shared by every folder and every wave). While at least one is held, the line of the live waves of `cadence orchestrate --status` and of `cadence lead tour` gains a segment and subtracts them: `vagues en cours : 1 · sessions en cours : 0 · sessions du lead : 1 (correctif-L12) · créneaux libres : 0 sur 3`. A held session alone is enough to print the line (`vagues en cours : 0`). It is a display, like the rest of the slots line: a hold blocks no session and never raises the cap (a wave that is already running keeps its own slot counting), and the `lead` skill declares every hand-started session with it.
+
+## The librarian by hand
+
+For a lot the lead delegated by hand, `raf check` or the `dérive` column of `cadence lead tour` reporting `documentation en retard` is
+handled before the review, as an orchestrated wave does it: the lead hands the project (absolute path) and the lot id to the
+`doc-keeper` agent ([skills](skills.md), [news](news.md#the-librarian-doc-keeper)), in a writing session, or read-only when it
+only wants the list of the documents to change (L306). A document outside the repository is named by the `docs.articles` key
+of the project's `cadence.yaml`, never guessed: the lead reads that key itself and puts its entries in the brief with the absolute path of each repository (the subagent is given read access to it), because the agent examines no outside document the brief does not name. The agent proposes a lot for the plan of that repository, in the `resume` of its
+report, and the lead decides whether to add it (`raf add` in that repository). The agent never writes to that plan.
+
 ## lead tour
 
 `cadence lead tour [folder] [--idle 3] [--depth n] [--json]` is the lead's morning table, with no model in
 the loop. From a parent folder (default: the current one) it takes every direct sub-folder that
-holds `docs/plan/raf.yaml`, or a `cadence.yaml` with a `plan:` key (a plan kept by another tool
-included), and for each one reads the same facts as `cadence session start` — in-process, no
+holds `.cadence/raf.yaml` or `docs/plan/raf.yaml`, or a `cadence.yaml` with a `plan:` key (a plan kept by another tool
+included; hidden folders, `node_modules` and `tmp/` — throwaway working copies — are skipped), and for each one reads the same facts as `cadence session start` — in-process, no
 sub-process, no call to `claude` — then prints **one line per project**:
 
 ```
-alpha · en cours L1 (silencieux 4j) · dérive 1 (✗ L2 a 1 commit(s) mais est encore todo) · notes : finir L1 puis livrer · prochain L3 Typo · dépôt non commité, non poussé
+alpha · en cours L1 (1 commit, silencieux 4j) · dérive 1 (✗ L2 a 1 commit(s) mais est encore todo) · notes : finir L1 puis livrer · prochain L3 Typo · dépôt non commité, non poussé
 beta · en cours rien · dérive aucune · notes : aucune · prochain T2 Second · dépôt propre
 ```
 
 | Column | Content |
 |---|---|
-| `en cours` | ids of the lots in progress; `(aucune activité)` when it has none at all, `(silencieux Nj)` when the lot's last activity (commit, note or start) is more than `--idle` days old (default 3) |
+| `en cours` | ids of the lots in progress, each with its number of commits (`0 commit` included: a close note on a lot without commit is not « done, `raf done` forgotten »); then `aucune activité` when it has no activity at all, `silencieux Nj` when the lot's last activity (commit, note or start) is more than `--idle` days old (default 3) |
 | `dérive` | the gaps `raf check` reports (a lot whose commits leave a document behind, [`docs.sync`](news.md#documentation-that-follows-the-code), included), counted and the first two shown |
 | `notes` | the notes left by the last `session close`, joined with ` / ` and cut at 120 characters |
 | `prochain` | the first ready lot (quick wins first) — id and title cut at 60 characters; a lot whose [`gate`](raf.md#plan-file) is not met is not ready |
 | `attend` | only when a lot waits on its `gate`: `attend L190` |
 | `dépôt` | `non commité` (modified or untracked files), `non poussé` (commits ahead of the upstream), `livraison en cours` (live delivery lock); `propre` otherwise |
 
+After the project lines the tour lists the **worktrees kept by waves** (L279, experimental mode, not enabled until L299–L301 are done; [`orchestrate.worktrees`](orchestrate.md#one-worktree-per-lot-orchestrateworktrees-l279)): a title, then one line per kept worktree — repository, lot, age, number of unintegrated commits, path — so that a lot handed back with unintegrated commits is never forgotten; nothing is printed when there is none (`--json`: `worktrees` on the project's row). `cadence orchestrate --status` and the final table of a wave print the same lines; the lead removes one with `cadence orchestrate --remove-worktree <project>:<lot> [--abandon-commits]`.
+
 Before the project lines the tour prints the **perf header** (L227): one line per `⚠` of `cadence perf` for the folder, in the order of `perf`, each ending with its decision and, for a trend, the value of its quality twin (speed and quality side by side); the net-bottleneck `⚠ goulot` line is relayed as is. Nothing is printed when no `⚠` stands, and the output is then the one of a tour without header. The header is read with `perf`'s own reading of the folder (projects up to two levels, whatever `--depth`) and only in the text output: `--json` is unchanged. When `perf` cannot read the folder (no `.cadence/runs`, malformed price grid, unreadable journals or plans) the tour prints no header, reports no perf error and exits 0. The [lead skill](skills.md) reads the header before proposing the three lots and opens an improvement lot only on a trend confirmed on two windows or a net bottleneck.
 
-When an orchestrated wave is live, one more line closes the tour (not part of `--json`): `vagues en cours : 1 · sessions en cours : 0 · créneaux libres : 1 sur 2` — the lead reads the free slots there instead of computing them (L141). The `sur M` is the cap the human set (`CADENCE_MAX_SESSIONS`, 2 by default), not a fixed 2 (L208); an invalid value falls back to 2 in this display.
+When an orchestrated wave is live, one more line closes the tour (not part of `--json`): `vagues en cours : 1 · sessions en cours : 0 · créneaux libres : 1 sur 2` — the lead reads the free slots there instead of computing them (L141). The `sur M` is the cap the human set (`CADENCE_MAX_SESSIONS`, 2 by default), not a fixed 2 (L208); an invalid value falls back to 2 in this display. The sessions held with [`lead hold`](#lead-hold-and-release) are subtracted from the free slots, and one alone is enough to print the line (L255).
+
+Next to it, when at least one ready lot is free, a line `prêts, ressources libres : alpha:L3 <title> · beta:L2 <title> (banc)` (L252, GitHub issue #13, 2/3) lists, for every project of the tour, the ready lots (same rule as `next`, minus the ones marked « à décider ») that can start now: a lot is free when none of the resources in its `uses:` (shown in parentheses) is held by a lot `doing` in any project of the tour or in any project that shares its resources (the projects under the folder whose `cadence.yaml` declares `resources:`, walked with that file's `depth:`, one level by default, so `P/x` and `P/grp/alpha` share the `banc` of `P/cadence.yaml` with `depth: 2` wherever the tour is launched from, even from inside one project; with no declared resource, the projects of the parent folder), nor by an unfinished lot of a live wave (a wave's lot is recognised by its repository and its id, not by the project name: a nested project `grp/alpha` matches the wave launched from `grp/` that cites it as `alpha`, and a wave launched from another folder only hides the lots of its own repositories); a lot with no `uses:` holds none and is always free. The line shows at most 3 lots per project, then `alpha +K` for the others. Like the slots line it prints while a wave is live, or as soon as a session is held with `lead hold` (L255); with neither, it stays silent. It is a display: nothing locks, `raf start` and `orchestrate` still start a lot whose resource is taken. `--json` gives the same lots, always, as a `free` array on each project (`id`, `title`, and `uses` when the lot has any; absent when the project has none).
+
+The `lead` skill (L253, GitHub issue #13, 3/3) tells the lead to read that line again each time an agent comes back and each time a lot is blocked, before waiting: a lot it lists can start at once, with the free slots line saying a slot is free, instead of waiting behind the blocked one. The line never raises the slot cap.
 
 `--json` prints the same content as an array of objects (`project`, `doing`, `drift`, `notes`, `waiting` (only when a lot waits on its `gate`),
+`free` (L252, above),
 `next`, `repo`, and `error` when the project could not be read), plus `progress` — `{ done, doing, todo, added7 }`,
 the lots done / in progress / to do (dropped and recurring lots left out) and those created in the last 7 days (L149), which
 [`cadence-hud`](../plugins/cadence-hud/README.md) draws as one progress bar per project. Projects come in the order of the

package/docs/news.md

@@ -150,10 +150,33 @@ to be reported as one **major** finding per line — a stale document is not lef
 memory of a sentence. Touching a document is what the program checks; whether its text is true is
 still the review's reading. The commits of neighbouring repositories (`repos:`) are not audited.
 
+### The librarian: `doc-keeper`
+
+`docs.sync` says *that* a document is behind; the `doc-keeper` agent (L306, `agents/doc-keeper.md`, generic: it knows no
+folder and no project) says *which* passage and writes it. Given a repository and a lot, it reads the diff of the lot
+(the commits that cite it), draws the map of the project's documents (the `docs.sync` rules, the README, the pages of
+`docs/`, the CHANGELOG, the news entries, the architecture document), lists the documents the change makes false or leaves
+out, then:
+
+- **writing session**: updates them and commits with explicit paths and `docs(<lot>): …`;
+- **read-only session** (no write tool, or a brief that says so): changes nothing and lists, document by document, the
+  passage to write.
+
+`cadence orchestrate` calls it by itself when `docs.sync` reports a document behind the commits of the lot, **before the
+review** (see « Librarian before the review » in [orchestrate](orchestrate.md)); the lead calls it by hand otherwise
+([lead](lead.md)).
+
+A document **outside the repository** is the librarian's only when the configuration names it, with the key that already
+names the project's article elsewhere, `docs.articles` (see below; absent by default): « this project is also described
+by this file of that repository ». The librarian reads that file (its repository is opened to the session for reading, and
+the brief gives its absolute path) and, when the change makes it false, **proposes a lot** for the plan of that repository
+(a title, then the file, the passage and the sentence to change) in the `resume` of its report, starting with
+« lot proposé ». It never edits that file and never writes to that plan: the lead decides whether the lot enters it.
+
 ### An article elsewhere that follows the delivery
 
 A case study that lives in a neighbouring repository (the project's article on a showcase site) goes stale
-the same way. `docs.articles` names it:
+the same way. `docs.articles` names it (`repo` absolute, or relative to the project):
 
 ```yaml
 docs: