@sylad/cadence 0.10.1 → 0.12.0

package/dist/state.js

@@ -61,38 +61,43 @@ export function readLock(dir) {
 export function lockAlive(lock) {
     return lock.unreadable ? lock.ageMs < 5_000 : pidAlive(lock.pid);
 }
-/** Pose le verrou de façon atomique (lien vers un fichier complet) ; false s'il existe déjà. */
-export function writeLock(dir, lock) {
-    const tmp = join(dir, `deliver.lock.${lock.pid}.${Date.now()}.tmp`);
-    writeFileSync(tmp, JSON.stringify(lock));
+/** Pose un fichier de façon atomique (lien vers un fichier complet : il n'existe jamais à moitié écrit) ; false s'il existe déjà (EEXIST) ; toute autre erreur est relancée. `tag` distingue les fichiers temporaires d'un même processus. */
+export function linkNewFile(file, content, tag) {
+    const tmp = `${file}.${tag}.${Date.now()}.tmp`;
+    writeFileSync(tmp, content);
     try {
-        linkSync(tmp, lockPath(dir));
+        linkSync(tmp, file);
         return true;
     }
-    catch {
-        return false;
+    catch (e) {
+        // Seul EEXIST veut dire « déjà là » ; EPERM, EMLINK… (pas de liens physiques ici) remontent au lieu de passer pour un verrou tenu.
+        if (e.code === 'EEXIST')
+            return false;
+        throw e;
     }
     finally {
         rmSync(tmp, { force: true });
     }
 }
-/** Retire un verrou périmé seulement s'il est encore celui qu'on a lu ; sinon le laisse en place. */
-export function removeStaleLock(dir, seen) {
-    const aside = join(dir, `deliver.lock.stale.${process.pid}`);
+/**
+ * Retire un verrou périmé seulement s'il est encore celui qu'on a lu : il est écarté par renommage, `same` relit
+ * l'écart, et s'il a changé il est rendu à son nouveau porteur. Partagé par le verrou de livraison et celui de l'URL UX.
+ */
+export function removeStaleFile(file, same) {
+    const aside = `${file}.stale.${process.pid}`;
     try {
-        renameSync(lockPath(dir), aside);
+        renameSync(file, aside);
     }
     catch {
         return false;
     }
-    const now = readLockFile(aside);
-    if (now && now.pid === seen.pid && now.sha === seen.sha && now.started === seen.started) {
+    if (same(aside)) {
         rmSync(aside, { force: true });
         return true;
     }
     // Un autre processus a pris le verrou entre-temps : le lui rendre.
     try {
-        linkSync(aside, lockPath(dir));
+        linkSync(aside, file);
     }
     catch {
         // Un troisième l'a déjà repris : le sien fait foi.
@@ -100,6 +105,21 @@ export function removeStaleLock(dir, seen) {
     rmSync(aside, { force: true });
     return false;
 }
+/** Cause d'une pose de verrou impossible, en une ligne : « verrou <chemin> : <errno> » (le code, sinon le message). */
+export function lockFault(file, e) {
+    return `verrou ${file} : ${e?.code ?? (e instanceof Error ? e.message : String(e))}`;
+}
+/** Pose le verrou de façon atomique (lien vers un fichier complet) ; false s'il existe déjà. */
+export function writeLock(dir, lock) {
+    return linkNewFile(lockPath(dir), JSON.stringify(lock), lock.pid);
+}
+/** Retire un verrou périmé seulement s'il est encore celui qu'on a lu ; sinon le laisse en place. */
+export function removeStaleLock(dir, seen) {
+    return removeStaleFile(lockPath(dir), (aside) => {
+        const now = readLockFile(aside);
+        return !!now && now.pid === seen.pid && now.sha === seen.sha && now.started === seen.started;
+    });
+}
 /** Retire le verrou s'il appartient à ce processus. */
 export function releaseLock(dir, pid) {
     const lock = readLock(dir);

package/package.json

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

package/skills/lead/SKILL.md

@@ -14,7 +14,13 @@ commands (its CLAUDE.md names them), never with `raf start|done|note|ux|review`.
 
 ## Limits that always apply
 
-- **At most two subagents running at once.** Queue the rest.
+- **At most two subagents running at once.** Queue the rest. The sessions of an orchestrated wave
+  (section 2b) count toward this limit: orchestrate sessions plus subagents never exceed two. A wave
+  already caps itself (`--max-sessions`, 2 by default, shared by every wave); before starting a
+  subagent, check `cadence orchestrate --status`, and while a wave runs, start none beyond the free
+  slots. Count the free slots from what `--status` shows per wave, not from the live sessions (a
+  wave's steps take a slot and give it back between two steps): 2 − Σ min(cap, number of repositories
+  of the wave that still have lots). Never raise `--max-sessions` above two to speed a wave up.
 - **Never two subagents in the same repository at the same time**, and the lead does not commit in a
   repository where a subagent is working.
 - **Deliveries and `raf ux` / `raf review` verdicts are done by the lead, one project at a time** —
@@ -35,11 +41,12 @@ progress, then drift that blocks a delivery, then ready quick wins. **Stop and w
 ## 2. Delegation
 
 The default way to delegate is **`cadence orchestrate`** (section 2b): a program, not a conversation, that runs
-one fresh short session per step. When the lead delegates by hand, the brief is the template
-`templates/orchestrate/implement.md` of the cadence package — the single source, tested; `cadence
-orchestrate --dry-run <project>:<lot>` writes it rendered for the lot. The lead runs
-`cd <project> && raf start <lot>`, fills `{{chemin}}`, `{{lot}}`, `{{titre}}` and `{{objectif}}` (what done
-looks like, from the human's words), and keeps the rest verbatim.
+one fresh short session per step; the wave runs from a frozen copy of the cadence package, so it can orchestrate cadence itself and its templates can be edited meanwhile. When the lead delegates by hand, the brief is the template
+`templates/orchestrate/implement.md` of the cadence package — the single source, tested. The lead runs
+`cd <project> && raf start <lot>`, then starts from the brief written by `cadence orchestrate --dry-run
+<project>:<lot>`: it is already rendered (`{{chemin}}`, `{{lot}}`, `{{titre}}`, `{{objectif}}` and `{{news}}`,
+the News instruction of a `visible` lot, are filled in; it names no wave Playwright directory — a hand delegation has none — so the screenshot goes under the OS temp directory, then into `docs/nouveautes/captures/`). The lead only adjusts the goal to what done looks
+like (the human's words) and keeps the rest verbatim.
 
 A lot that adds or changes a screen is `visible`: after the implementation, have the
 `ux-reviewer` agent review it (give it the URL or the way to run the app) and bring its verdict and
@@ -57,7 +64,9 @@ cadence orchestrate <project>:<lot> <project>:<lot>@haiku … [--budget 2M]
 `cadence orchestrate --dry-run …` first when a precondition is in doubt. The program, not the lead, runs
 for each lot a fresh short session per step — implementation (Sonnet), UX review if the lot is `visible`
 and the project declares how to see its app (`orchestrate.ux` in `cadence.yaml`), code review last
-(Opus, the `code-reviewer` agent), a correction in a new session if the review is not compliant (two
+(Opus, the `code-reviewer` agent; Sonnet, with no pass on the minor findings, for a lot whose estimate is
+≤ 0.25 d — `orchestrate.review` in `cadence.yaml`; a blocker or major finding still brings a correction and an
+Opus review), a correction in a new session if the review is not compliant (two
 passes at most) — and records `raf review` itself when the code review is compliant. The state is in
 `.cadence/runs/<wave>/`, not in this conversation. `@haiku` only when the human writes it, for a
 mechanical lot. Exit code: 0 all ready · 1 some lots handed back · 2 refused before acting · 3 wave
@@ -67,7 +76,7 @@ What the orchestrator does **not** do, and stays with the lead: choose the lots
 questions back (`--resume --answer <project>:<lot> "…"`), look at the UX reviewer's captures and record
 `raf ux` (the orchestrator reports its verdict, it never records it), re-verify (section 3, point 2),
 `raf done`, push and deliver. Minor findings and proposed sub-tasks come back in the table: adding them to
-the plan is the lead's decision. If an orchestrated wave is running in a repository, do not commit there
+the plan is the lead's decision. A minor finding becomes a lot of its own only if it describes an observable bug (a wrong output, a crash, a measured regression); otherwise it stays a note of the originating lot, so that a review never feeds the next one. If an orchestrated wave is running in a repository, do not commit there
 and do not deliver it (`cadence deliver` refuses).
 
 ## 3. Check

package/templates/orchestrate/fix-minors.md

@@ -17,6 +17,9 @@ Minor choices to settle yourself, writing the alternative you did not take:
 a spacing, colour or label value when a measurement or a rule justifies it; the URL of a link (the most general official page if a precise one is not certain);
 a News entry: only if a finding asks for it; a written rule of the project's CLAUDE.md (apply it); who launches the review or UX pass (never the session: the program and the lead do).
 "not my job to touch the plan" is not a question: say it in the report.
+Never stop to ask about how to organise your own work (split or squash a commit, whether to continue): decide, list it under "choix", go on. A finding you contest is noted under "choix" with the evidence, not raised to the lead.
 You are one short session of an orchestrated wave: do not launch subagents (the Agent tool is disabled).
 Give your final report as the structured output (commits, tests, build, what you could not verify, choices).
 {{reponse}}
+{{captures}}
+Browser (Playwright): if a Playwright MCP server is available in this session, it was launched by the orchestrator with its own output directory, in the orchestrator's run directory outside the repository: give screenshots, snapshots and traces a relative file name only (e.g. `page-home.png`), they land there. Never an absolute path, never the `--output-dir` option (the server's launch argument, which a session cannot set). If no such server is available, do not install or start one; if you use the Playwright CLI, write its outputs under the OS temp directory (or the temporary folder the project's CLAUDE.md names), never inside the repository, which must stay clean.

package/templates/orchestrate/fix.md

@@ -16,6 +16,10 @@ otherwise it is a choice: decide, write the alternative you did not take, go on.
 a spacing, colour or label value when a measurement or a rule justifies it; the URL of a link (the most general official page if a precise one is not certain);
 a News entry: only if a finding asks for it; a written rule of the project's CLAUDE.md (apply it); who launches the review or UX pass (never the session: the program and the lead do).
 "not my job to touch the plan" is not a question: say it in the report.
+Never stop to ask about how to organise your own work (split or squash a commit, order of the sub-parts, whether to continue, "I have no question"): decide, list it under "choix", go on. Leave "questions" empty rather than writing a placeholder such as "no question".
+A finding you contest (it describes a state older than the code, or you think it wrong) is not a question and not a reason to stop: do not ask the lead to arbitrate. Write it under "choix" with the evidence (the command, the line, the commit), fix what is right, go on; the next fresh review re-reads it.
 You are one short session of an orchestrated wave: do not launch subagents (the Agent tool is disabled).
 Give your final report as the structured output (commits, tests, build, what you could not verify, choices, questions).
 {{reponse}}
+{{captures}}
+Browser (Playwright): if a Playwright MCP server is available in this session, it was launched by the orchestrator with its own output directory, in the orchestrator's run directory outside the repository: give screenshots, snapshots and traces a relative file name only (e.g. `page-home.png`), they land there. Never an absolute path, never the `--output-dir` option (the server's launch argument, which a session cannot set). If no such server is available, do not install or start one; if you use the Playwright CLI, write its outputs under the OS temp directory (or the temporary folder the project's CLAUDE.md names), never inside the repository, which must stay clean.

package/templates/orchestrate/implement.md

@@ -5,14 +5,16 @@ Rules: test first; commit each sub-part as soon as its tests pass, with explicit
 `git add -A` or `commit -a`), and a message that cites the lot (`feat({{lot}}): …`); run the project's
 full test suite and build before reporting; do not push, deliver, run `raf done`, `raf ux` or
 `raf review`.
+Documentation: the project's README (and its usage documentation) describes the behaviour you deliver, updated in the same commits, like the CHANGELOG — a README that does not follow your change is a major finding of the review.
 Decide minor interpretation questions yourself (the wording of a message, a name, a default, the
 reading of an ambiguous line of the lot) and list each one under "choix" in your report, with the
 alternative you did not take — the reviewer re-reads them. Stop and ask (under "questions") only on a real blocker.
 A question is legitimate only if it names what it would change: the scope of the lot, the architecture, or a costly rollback (data, production, public API), AND the plan, its notes and the project's CLAUDE.md do not settle it;
 otherwise it is a choice: decide, write the alternative you did not take, go on. Minor choices to settle yourself:
 a spacing, colour or label value when a measurement or a rule justifies it; the URL of a link (the most general official page if a precise one is not certain);
-a News entry for a visible lot (yes, always); a written rule of the project's CLAUDE.md (apply it); who launches the review or UX pass (never the session: the program and the lead do).
+a written rule of the project's CLAUDE.md (apply it); who launches the review or UX pass (never the session: the program and the lead do).
 "not my job to touch the plan" is not a question: say it in the report.
+Never stop to ask about how to organise your own work (split or squash a commit, order of the sub-parts, whether to continue, "I have no question"): decide, list it under "choix", go on. Leave "questions" empty rather than writing a placeholder such as "no question".
 If the lot's commits already cover its open sub-tasks, do not ask whether to continue: make no commit and say so
 in your report (the review that follows re-reads those commits). If they do not cover them all, implement the rest.
 Report: commits (sha + subject), tests and build results with their numbers, what you could not
@@ -21,5 +23,7 @@ verify, choices made, open questions.
 You are one short session of an orchestrated wave: do not launch subagents (the Agent tool is disabled).
 Give your final report as the structured output, not as free text. If the plan is kept by the project's own tool
 (read-only for `raf`), use that tool's commands named in the project's CLAUDE.md, never `raf start|done|note`.
+{{news}}
 {{commits}}
 {{reponse}}
+Browser (Playwright): if a Playwright MCP server is available in this session, it was launched by the orchestrator with its own output directory, in the orchestrator's run directory outside the repository: give screenshots, snapshots and traces a relative file name only (e.g. `page-home.png`), they land there. Never an absolute path, never the `--output-dir` option (the server's launch argument, which a session cannot set). If no such server is available, do not install or start one; if you use the Playwright CLI, write its outputs under the OS temp directory (or the temporary folder the project's CLAUDE.md names), never inside the repository, which must stay clean.

package/templates/orchestrate/precheck.md

@@ -0,0 +1,10 @@
+Pre-check for lot `{{lot}}` — "{{titre}}" — of the repository `{{chemin}}`, as the read-only pre-check reader.
+Question: is the deliverable of this lot ALREADY in the repository (done by another lot, or by a correction)?
+Goal of the lot: {{objectif}}
+Read the lot, its notes and sub-tasks in the plan (`docs/plan/raf.yaml`, or the file named by `plan:` in `cadence.yaml`),
+then look for the deliverable in the code and tests (`git log`, `grep`, reading the files the lot names). Do not
+implement anything and do not run the full test suite: this is a quick look.
+Answer `oui` only when every part of the lot is present, with a proof for each (file:line or commit sha); `partiel` when
+some parts are present (say which); `non` otherwise. When in doubt, answer `non`: an implementation session follows.
+You are read-only: do not modify, commit, push or run `raf start|done|note|review|ux`. Do not launch subagents.
+Give your report as the structured output: `dejaPresent` (oui | partiel | non), `preuves` (the proofs), `resume` (one sentence).

package/templates/orchestrate/review-recheck.md

@@ -4,7 +4,9 @@ treated them. Check that the minor findings fixed are fixed, that the fixes brok
 rest of the lot is still sound: read the diff yourself from the commits that cite the lot
 (`raf commits {{lot}}`, or `git log`), run the checks, report real defects only. A new minor finding
 is reported, not a reason to ask for another pass. This is a code review only.
+{{checks}}
 {{choix}}
+A proposed sub-task describes an observable bug (a wrong output, a crash, a measured regression); any other minor finding stays a note of this lot, not a sub-task.
 You are read-only: do not modify, commit, push or run `raf review|ux|done`. Do not launch subagents.
 Give your report as the structured output: counts of blocking / major / minor findings, each finding
 (severity, file, line, text), proposed sub-tasks, what you could not verify, and the one-line verdict

package/templates/orchestrate/review-small.md

@@ -3,9 +3,12 @@ This lot is small: one single pass covers the code review AND the usability revi
 You are given the repository path and the lot id only: read the diff yourself from the commits that
 cite the lot (`raf commits {{lot}}`, or `git log`), run the checks, report real defects only.
 {{ux}}
+{{checks}}
 {{choix}}
+A proposed sub-task describes an observable bug (a wrong output, a crash, a measured regression); any other minor finding stays a note of this lot, not a sub-task.
 You are read-only: do not modify, commit, push or run `raf review|ux|done`. Do not launch subagents.
 Give your report as the structured output: counts of blocking / major / minor findings (usability
 findings included, each tied to a named rule — Nielsen heuristic or WCAG 2.2 AA criterion — or a
 measurement), each finding (severity, file, line, text), proposed sub-tasks, what you could not
 verify, and the one-line verdict for `raf review {{lot}}`.
+Browser (Playwright): if a Playwright MCP server is available in this session, it was launched by the orchestrator with its own output directory, in the orchestrator's run directory outside the repository: give screenshots, snapshots and traces a relative file name only (e.g. `page-home.png`), they land there. Never an absolute path, never the `--output-dir` option (the server's launch argument, which a session cannot set). If no such server is available, do not install or start one; if you use the Playwright CLI, write its outputs under the OS temp directory (or the temporary folder the project's CLAUDE.md names), never inside the repository, which must stay clean.

package/templates/orchestrate/review.md

@@ -1,7 +1,9 @@
 Review lot `{{lot}}` — "{{titre}}" — of the repository `{{chemin}}`, following your agent instructions.
 You are given the repository path and the lot id only: read the diff yourself from the commits that
 cite the lot (`raf commits {{lot}}`, or `git log`), run the checks, report real defects only.
+{{checks}}
 {{choix}}
+A proposed sub-task describes an observable bug (a wrong output, a crash, a measured regression); any other minor finding stays a note of this lot, not a sub-task.
 You are read-only: do not modify, commit, push or run `raf review|ux|done`. Do not launch subagents.
 Give your report as the structured output: counts of blocking / major / minor findings, each finding
 (severity, file, line, text), proposed sub-tasks, what you could not verify, and the one-line verdict

package/templates/orchestrate/ux.md

@@ -2,9 +2,11 @@ Review the usability and accessibility of lot `{{lot}}` — "{{titre}}" — of t
 following your agent instructions. Read the diff yourself from the commits that cite the lot
 (`raf commits {{lot}}`, or `git log`).
 {{ux}}
+A proposed sub-task describes an observable bug (a wrong output, a crash, a measured regression); any other minor finding stays a note of this lot, not a sub-task.
 You are read-only: do not modify, commit, push or run `raf review|ux|done`. Do not launch subagents.
 Ground every finding in a named rule (Nielsen heuristic, WCAG 2.2 AA criterion) or a measurement;
 describe a mockup before proposing any redesign, never code it.
 Give your report as the structured output: counts of blocking / major / minor findings, each finding
 (severity, file, line, text), proposed sub-tasks, what you could not verify, and the one-line verdict
 for `raf ux {{lot}}`.
+Playwright (browser MCP): this session's Playwright server was launched by the orchestrator with its own output directory, which lies in the orchestrator's run directory, outside the repository. Every screenshot, snapshot and trace you take lands there, so give each one a relative file name only (e.g. `page-home.png`, `home-390px.png`): the lead will look at them in that directory. Never an absolute path (such as one under `/tmp`), never the `--output-dir` option (it is the server's launch argument, which a session cannot set), and never write browser outputs anywhere else; the repository must stay clean.