@sylad/cadence 0.7.0 → 0.9.0

package/dist/verify.js

@@ -0,0 +1,114 @@
+import { spawn } from 'node:child_process';
+import { constants } from 'node:os';
+import { onTermination } from './proc.js';
+import { describeCheck, realDeps, retryCheck, TIMED_OUT } from './deliver.js';
+function killGroup(pgid, sig) {
+    try {
+        process.kill(-pgid, sig);
+    }
+    catch {
+        // groupe déjà vide
+    }
+}
+/**
+ * Une commande de vérification, en groupe de processus détaché (nouvelle session, sans tty) : au délai,
+ * TOUT le groupe est tué (aucun enfant orphelin) ; un signal reçu par cadence lui est relayé. Asynchrone :
+ * les vérifications tournent en parallèle. Réservé aux vérifications (verify, session start) — jamais
+ * aux commandes de deliver, qui gardent le groupe de premier plan et le tty.
+ */
+function execGroup(root, cmd, env, timeoutMs, quiet) {
+    return new Promise((resolve) => {
+        const child = spawn('sh', ['-c', cmd], {
+            cwd: root,
+            env: { ...process.env, ...env },
+            stdio: quiet ? 'ignore' : ['ignore', 'inherit', 'inherit'],
+            detached: true,
+        });
+        const pgid = child.pid;
+        if (pgid === undefined) {
+            child.once('error', () => resolve(127));
+            return;
+        }
+        // Ctrl-C, SIGTERM ou raccrochage reçu par cadence : relayé au groupe avant de sortir.
+        const forget = onTermination((sig) => killGroup(pgid, sig));
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            killGroup(pgid, 'SIGKILL');
+        }, timeoutMs);
+        child.once('exit', (code, signal) => {
+            clearTimeout(timer);
+            forget();
+            if (timedOut)
+                killGroup(pgid, 'SIGKILL'); // sh mort avant ses enfants : le groupe est vidé quand même
+            resolve(timedOut ? TIMED_OUT : signal ? 128 + (constants.signals[signal] ?? 0) : (code ?? 1));
+        });
+    });
+}
+/** Dépendances réelles des vérifications. `quiet` : sortie des commandes non relayée (rapport de session start). */
+export function realCheckDeps(root, opts = {}) {
+    const { fetch, sleep, now } = realDeps(root);
+    return { fetch, sleep, now, exec: (cmd, env, timeoutMs) => execGroup(root, cmd, env, timeoutMs, !!opts.quiet) };
+}
+/**
+ * Rejoue des vérifications d'effet, TOUTES EN PARALLÈLE : chaque essai reçoit le budget entier
+ * (`attemptMs`, tuée au-delà : « délai dépassé »), une vérification lente ne prend rien aux autres.
+ * UNE passe par défaut ; avec `retryMs`, chacune est réessayée de son côté (toutes les POLL_VERIFY)
+ * jusqu'à ce délai. Durée totale bornée par retryMs + attemptMs. Résultats dans l'ordre des vérifications.
+ * Le code d'une vérification est celui de deliver (tryCheck/retryCheck) : aucune règle n'est dupliquée.
+ */
+export async function replayChecks(checks, deps, sha, env, opts) {
+    const until = deps.now() + opts.retryMs;
+    return Promise.all(checks.map(async (c) => ({ label: describeCheck(c, sha), reason: await retryCheck(c, deps, sha, env, until, () => opts.attemptMs) })));
+}
+export const resultLine = (r) => (r.reason === null ? `✓ ${r.label}` : `✗ ${r.label} — ${r.reason}`);
+export function summaryLine(results) {
+    const red = results.filter((r) => r.reason !== null).length;
+    const n = results.length;
+    return red === 0
+        ? `verify : ${n}/${n} vérifications vertes`
+        : `verify : ${red} effet${red > 1 ? 's' : ''} rouge${red > 1 ? 's' : ''} sur ${n} vérification${n > 1 ? 's' : ''}`;
+}
+/** Variables passées aux commandes de vérification, comme à celles de deliver. */
+export function verifyEnv(sha) {
+    return { CADENCE_SHA: sha, CADENCE_SHORT: sha.slice(0, 7), CADENCE_BRANCH: '' };
+}
+/** Délai de chaque essai d'une vérification de `cadence verify`. */
+export const VERIFY_ATTEMPT_MS = 120_000;
+/** `cadence verify` : 0 tout vert, 1 un effet rouge, 2 rien à vérifier. */
+export async function verifyCommand(ctx, deps) {
+    const { config, out } = ctx;
+    if (config.verify.length === 0) {
+        out(config.script !== undefined
+            ? 'verify : aucune vérification déclarée — ce projet livre par son script (deliver.script) et ses contrôles sont les siens ; ' +
+                'déclarer deliver.verify dans cadence.yaml pour les rejouer hors livraison'
+            : 'verify : aucune vérification déclarée (deliver.verify)');
+        return 2;
+    }
+    const results = await replayChecks(config.verify, deps, ctx.sha, verifyEnv(ctx.sha), { retryMs: ctx.retry * 1000, attemptMs: VERIFY_ATTEMPT_MS });
+    for (const r of results)
+        out(resultLine(r));
+    out(summaryLine(results));
+    return results.some((r) => r.reason !== null) ? 1 : 0;
+}
+/**
+ * Délai de chaque vérification de « session start », lancées en parallèle : c'est aussi, à la mise à mort
+ * près, la durée totale — la reprise ne doit pas attendre un réseau absent.
+ */
+export const MORNING_BUDGET_MS = 10_000;
+/**
+ * Lignes « Effets en production » du rapport de reprise : un seul essai par vérification, borné. Rien à dire
+ * (liste vide) pour un projet sans verify ; ne lève jamais — c'est un fait de plus, pas une condition.
+ */
+export async function effectLines(config, sha, deps) {
+    if (config.verify.length === 0)
+        return [];
+    try {
+        const results = await replayChecks(config.verify, deps, sha, verifyEnv(sha), { retryMs: 0, attemptMs: MORNING_BUDGET_MS });
+        const shown = results.filter((r) => r.reason !== null);
+        return shown.length === 0 ? [`✓ ${summaryLine(results)}`] : [...shown.map(resultLine), summaryLine(results)];
+    }
+    catch (e) {
+        return [`✗ verify : ${e.message}`];
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sylad/cadence",
-  "version": "0.7.0",
+  "version": "0.9.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",
@@ -9,8 +9,19 @@
     "raf": "bin/raf.js",
     "cadence": "bin/cadence.js"
   },
-  "files": ["bin", "dist", "skills", "agents", ".claude-plugin", "README.md", "LICENSE"],
-  "engines": { "node": ">=20" },
+  "files": [
+    "bin",
+    "dist",
+    "skills",
+    "agents",
+    "templates",
+    ".claude-plugin",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "test": "vitest run",
@@ -25,5 +36,9 @@
     "@types/node": "^20.14.0",
     "typescript": "^5.5.0",
     "vitest": "^2.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Sylad/cadence.git"
   }
 }

package/skills/lead/SKILL.md

@@ -34,26 +34,46 @@ progress, then drift that blocks a delivery, then ready quick wins. **Stop and w
 
 ## 2. Delegation
 
-For each chosen lot, the lead runs `cd <project> && raf start <lot>`, then gives a subagent this brief
-(fill in the brackets, keep the rest verbatim):
-
-> Work in `<absolute path of the project>` on lot `<id>` — "<title>" — of its plan
-> (`docs/plan/raf.yaml`, or the file named by `plan:` in `cadence.yaml`; read the lot, its notes and sub-tasks, and the project's CLAUDE.md first).
-> Goal: <what done looks like, from the human's words>.
-> Rules: test first; commit each sub-part as soon as its tests pass, with explicit paths (never
-> `git add -A` or `commit -a`), and a message that cites the lot (`feat(<id>): …`); run the project's
-> full test suite and build before reporting; do not push, deliver, run `raf done`, `raf ux` or
-> `raf review`.
-> If something is ambiguous or needs a decision, stop and report the question instead of guessing.
-> Report: commits (sha + subject), tests and build results with their numbers, what you could not
-> verify, open questions.
+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.
 
 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
 proposed sub-tasks back to the human.
 
+### 2b. A wave through `cadence orchestrate`
+
+Once the human has chosen the lots, the lead runs, **in the background** (it is notified at the end; no
+silent wait, no polling loop — `cadence orchestrate --status` shows where the wave is):
+
+```sh
+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
+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
+suspended (budget or usage limit; `--resume --budget …` continues).
+
+What the orchestrator does **not** do, and stays with the lead: choose the lots (with the human), bring the
+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
+and do not deliver it (`cadence deliver` refuses).
+
 ## 3. Check
 
+0. After an orchestrated wave the review is already done, by a fresh session: read the table, then go to
+   point 2. For a lot delegated by hand:
 1. The `code-reviewer` agent, as a fresh subagent (most capable model), reviews the lot. Give it
    the absolute path of the project and the lot id, **not** the author's report: it reads the diff
    itself from the commits that cite the lot, runs the checks, and returns real defects only,

package/skills/session-close/SKILL.md

@@ -34,18 +34,39 @@ With no project named, run `cadence session close` in each project touched durin
      (`raf review enable`), UX review of a visible lot (`raf ux enable`) → have the `code-reviewer` / `ux-reviewer` agent review it, then record its
      verdict with `raf review <id> "…"` / `raf ux <id> "…"`; never write a verdict nobody gave;
    - rerun until the check part is clean.
-3. **Memory, filtered** (only if you keep a persistent memory): write down what the repository does
+3. **Stale working files** (report section "Nettoyage proposé", from `session.clean` in `cadence.yaml`):
+   list them to the human — shared tmp folder, screenshots no one refers to, throwaway scripts,
+   folders left by tests — and delete them only after the human agrees, with explicit paths (never a
+   wildcard `rm`, never a file `git` tracks). The agreement can be old by then: right before
+   deleting, re-run `cadence session close` (or the scan) and delete only the entries that are
+   still proposed, never one the human named from memory. Delete a proposed symbolic link as a
+   link (`rm path`, no trailing `/`, never `rm -r` through it). Before proposing a screenshot, check nothing still
+   refers to it (plan, news, docs). Anything kept: leave it, it will be listed again next close. No
+   section: nothing to do; a project with no `session.clean` can propose adding it.
+   An entry is proposed only if it could be measured entirely. Age: a folder's age is that of the
+   most recent entry it contains, an entry's age counting from the later of its modification and status-change times. The report never proposes: a git repository, a folder that
+   contains one at any depth, and anything under a `.git` folder; a git directory without a `.git`
+   entry (bare repository, mirror, `--separate-git-dir`, worktree admin folder — recognised by
+   `HEAD` with `objects` and `refs`, or with `commondir`), anything inside it or a folder that
+   contains one; anything `git` tracks, in any repository that has a `.git` entry above it (one limit: a bare repository driven with an external work tree, `git --git-dir=~/.dotfiles --work-tree=~`, leaves no `.git` beside its files — their tracked files can be proposed, so check a proposed entry is not one); a name starting with `.`
+   unless the pattern itself starts that name with `.`; anything behind a symbolic link a `*`
+   matched (the link itself may be proposed: remove the link, never `rm -r` through it — a segment
+   written in full before the first `*` does follow its link); the repository itself or a folder that contains it;
+   anything that could not be read entirely — those are listed apart as "illisible(s)": tell the
+   human, never delete those, and never widen the list by hand to entries the report did not
+   propose.
+4. **Memory, filtered** (only if you keep a persistent memory): write down what the repository does
    NOT already say — a trap and its cause, a decision or correction from the human, a collaboration
    rule. Test: "do `git log` or the docs already say it?" → then no memory.
-4. **Skills and agents, on threshold, PROPOSED**: a skill when the same chain of commands was done by
+5. **Skills and agents, on threshold, PROPOSED**: a skill when the same chain of commands was done by
    hand at least twice today; an agent update when an agent got something wrong or its domain moved.
    List them with the benefit; the human decides. Never create them here.
    When the report has a "Faits propres au projet" section (`session.close` in `cadence.yaml`), treat
    what it flags as part of this hygiene; with a read-only plan, use the project's own tool wherever
    these steps say `raf`.
-5. **Clean state**: everything committed and pushed, no delivery running. If the command still exits 1,
+6. **Clean state**: everything committed and pushed, no delivery running. If the command still exits 1,
    say what remains and do NOT say the session is closed.
-6. **Three lines for next time**: `cadence session next "…" "…" "…"` — the next `session-start` shows them.
+7. **Three lines for next time**: `cadence session next "…" "…" "…"` — the next `session-start` shows them.
    The lines replace the previous notes. Without a line the command refuses and keeps them; erase
    them on purpose with `cadence session next --clear`, only when nothing is left to say.
 

package/skills/session-start/SKILL.md

@@ -30,6 +30,9 @@ three most useful items across projects and wait. With a project named, work in
    - **Done since**: 3 to 6 lines, grouped by lot, not by commit. Mention commits without a lot.
    - **Drift**: each `✗` line from the check, with the one command that fixes it.
    - **Delivery in progress** or a stale lock: no new delivery until it is resolved.
+   - **Effects in production** ("Effets en production"): a red `✗` line is the first thing to say —
+     a delivered feature that no longer works outranks any new lot; re-run `cadence verify` to confirm
+     (a network blip also shows as red).
    - **Notes from the last close**, if any.
    - **Project facts** ("Faits propres au projet"), when the project plugs its own morning script in
      (`session.start` in `cadence.yaml`): summarise what bears on today's choice — deadlines, the

package/templates/orchestrate/fix-minors.md

@@ -0,0 +1,18 @@
+Work in `{{chemin}}` on lot `{{lot}}` — "{{titre}}" — of its plan.
+A fresh review found only minor findings: the lot is compliant, and this is the one pass that treats them.
+Commits of the lot so far:
+{{commits}}
+
+Minor findings:
+{{constats}}
+
+Fix each minor finding that is right, and nothing else. Rules: test first; commit each fix as soon as
+its tests pass, with explicit paths (never `git add -A` or `commit -a`), and a message that cites the
+lot (`fix({{lot}}): …`); run the project's full test suite and build before reporting; do not push,
+deliver, run `raf done`, `raf ux` or `raf review`. Read the project's CLAUDE.md first.
+Do not stop to ask. A finding that is wrong, or not worth its change, is not fixed: list it under
+"choix" in your report with the reason — the reviewer re-reads it and the lead sees it. Leave
+"questions" empty. Making no commit at all is a valid outcome when every finding is rejected.
+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}}

package/templates/orchestrate/fix.md

@@ -0,0 +1,16 @@
+Work in `{{chemin}}` on lot `{{lot}}` — "{{titre}}" — of its plan. A fresh review of the commits
+of this lot found the defects below; fix them, and nothing else.
+Commits of the lot so far:
+{{commits}}
+
+Findings to fix:
+{{constats}}
+
+Rules: test first; commit each fix as soon as its tests pass, with explicit paths (never
+`git add -A` or `commit -a`), and a message that cites the lot (`fix({{lot}}): …`); run the project's
+full test suite and build before reporting; do not push, deliver, run `raf done`, `raf ux` or
+`raf review`. Read the project's CLAUDE.md first.
+If a finding is wrong, or fixing it needs a decision, stop and report the question instead of guessing.
+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, questions).
+{{reponse}}

package/templates/orchestrate/implement.md

@@ -0,0 +1,20 @@
+Work in `{{chemin}}` on lot `{{lot}}` — "{{titre}}" — of its plan
+(`docs/plan/raf.yaml`, or the file named by `plan:` in `cadence.yaml`; read the lot, its notes and sub-tasks, and the project's CLAUDE.md first).
+Goal: {{objectif}}
+Rules: test first; commit each sub-part as soon as its tests pass, with explicit paths (never
+`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`.
+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 decision that changes the scope or the architecture, is costly to undo, or that the plan, its notes
+and the project's CLAUDE.md do not settle.
+Report: commits (sha + subject), tests and build results with their numbers, what you could not
+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`.
+{{commits}}
+{{reponse}}

package/templates/orchestrate/review-recheck.md

@@ -0,0 +1,11 @@
+Do a short re-review of lot `{{lot}}` — "{{titre}}" — of the repository `{{chemin}}`, following your
+agent instructions. A full review found the lot compliant with minor findings, and one pass has since
+treated them. Check that the minor findings fixed are fixed, that the fixes broke nothing, and that the
+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.
+{{choix}}
+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
+for `raf review {{lot}}`.

package/templates/orchestrate/review-small.md

@@ -0,0 +1,11 @@
+Review lot `{{lot}}` — "{{titre}}" — of the repository `{{chemin}}`, following your agent instructions.
+This lot is small: one single pass covers the code review AND the usability review.
+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}}
+{{choix}}
+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}}`.

package/templates/orchestrate/review.md

@@ -0,0 +1,8 @@
+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.
+{{choix}}
+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
+for `raf review {{lot}}`.

package/templates/orchestrate/ux.md

@@ -0,0 +1,10 @@
+Review the usability and accessibility of lot `{{lot}}` — "{{titre}}" — of the repository `{{chemin}}`,
+following your agent instructions. Read the diff yourself from the commits that cite the lot
+(`raf commits {{lot}}`, or `git log`).
+{{ux}}
+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}}`.