@sylad/cadence 0.2.0 → 0.6.0

package/dist/plan.js

@@ -5,6 +5,7 @@ import { isDay, toDay } from './dates.js';
 export const STATUSES = ['todo', 'doing', 'done', 'dropped'];
 export class RafError extends Error {
 }
+export const FIELDS = ['id', 'title', 'status', 'estimate', 'quickwin', 'visible', 'after', 'created', 'started', 'finished', 'notes', 'parent'];
 export function isOpen(status) {
     return status === 'todo' || status === 'doing';
 }
@@ -33,12 +34,24 @@ export class Plan {
     path;
     doc;
     indentSeq;
+    settings;
     constructor(path, doc, 
     /** false quand le fichier écrit à la main met les « - » en colonne de la clé parente. */
-    indentSeq) {
+    indentSeq, settings = {}) {
         this.path = path;
         this.doc = doc;
         this.indentSeq = indentSeq;
+        this.settings = settings;
+    }
+    /** Un plan lu dans un autre format ne change pas : sa lecture et le motif de ses références sont gardés. */
+    foreign;
+    get readonly() {
+        return !!this.settings.format;
+    }
+    writable() {
+        if (this.readonly) {
+            throw new RafError(`plan en lecture seule : ${this.path} est tenu par un autre outil (cadence.yaml : plan) — le modifier avec l'outil du projet`);
+        }
     }
     static create(path, project, prefix = 'L', since) {
         if (existsSync(path))
@@ -49,7 +62,7 @@ export class Plan {
         writeFileSync(path, initialContent(project, prefix, since ?? toDay(new Date())));
         return Plan.load(path);
     }
-    static load(path) {
+    static load(path, settings = {}) {
         if (!existsSync(path))
             throw new RafError(`pas de plan à ${path} — lancer « raf init »`);
         const text = readFileSync(path, 'utf8');
@@ -58,27 +71,90 @@ export class Plan {
             throw new RafError(`${path} : ${doc.errors[0].message}`);
         if (!isMap(doc.contents))
             throw new RafError(`${path} : la racine doit être un objet`);
+        if (settings.format) {
+            const key = settings.format.lots;
+            if (!isSeq(doc.get(key)))
+                throw new RafError(`${path} : la clé « ${key} » doit porter la liste des lots (cadence.yaml : plan.lots)`);
+            return new Plan(path, doc, true, settings);
+        }
         const lots = doc.get('lots');
         if (!isSeq(lots))
             doc.set('lots', doc.createNode([]));
         else
             lots.flow = false; // « lots: [] » écrit par init : passer en style bloc
-        return new Plan(path, doc, !/^lots:[^\n]*\n(?:#[^\n]*\n)*- /m.test(text));
+        return new Plan(path, doc, !/^lots:[^\n]*\n(?:#[^\n]*\n)*- /m.test(text), settings);
     }
     save() {
+        this.writable();
         writeFileSync(this.path, this.doc.toString({ lineWidth: 0, indentSeq: this.indentSeq }));
     }
     get project() {
-        return String(this.doc.get('project') ?? '');
+        return String(this.doc.get('project') ?? this.settings.project ?? '');
     }
     get prefix() {
         return String(this.doc.get('prefix') ?? 'L');
     }
     /** Date d'adoption de raf : les commits plus anciens ne sont pas audités. */
     get since() {
-        const v = this.doc.get('since');
+        const v = this.doc.get('since') ?? this.settings.since;
         return v == null ? undefined : String(v);
     }
+    /** Motifs (expressions régulières sur le sujet) des commits automatiques à ne pas auditer. */
+    get ignore() {
+        const raw = this.doc.get('ignore');
+        const own = isSeq(raw) ? raw.toJSON().map(String) : raw == null ? [] : [String(raw)];
+        const list = [...own, ...(this.settings.ignore ?? [])];
+        const patterns = [];
+        const invalid = [];
+        for (const src of list) {
+            try {
+                patterns.push(new RegExp(src));
+            }
+            catch {
+                invalid.push(src);
+            }
+        }
+        return { patterns, invalid };
+    }
+    /** Fichiers tenus avec le plan, relatifs à la racine du dépôt. */
+    get files() {
+        return this.settings.files ?? [];
+    }
+    /**
+     * Références citées par un texte. Format de raf : préfixe et numéro (`L3`, `L3/t1`). Autre format :
+     * les identifiants du plan eux-mêmes, quelle que soit leur forme (`E-A2`, `NC2.4`, `B33/t1-fusion`).
+     */
+    refs = (text) => {
+        if (!this.settings.format)
+            return extractRefs(text, this.prefix);
+        const { refs, tasks, ids } = this.read();
+        if (!refs)
+            return [];
+        return [...text.matchAll(refs)].flatMap((m) => {
+            if (!m[2])
+                return [{ lot: m[1] }];
+            if (tasks.has(`${m[1]}/${m[2]}`))
+                return [{ lot: m[1], task: m[2] }];
+            // « B33/E-A2 » : deux lots séparés par une barre, pas une sous-tâche.
+            return ids.has(m[2]) ? [{ lot: m[1] }, { lot: m[2] }] : [{ lot: m[1] }];
+        });
+    };
+    read() {
+        if (!this.foreign) {
+            const raw = this.doc.get(this.settings.format.lots).toJSON();
+            const lots = foreignLots(raw, this.settings.format);
+            const ids = lots.map((l) => l.id).sort((a, b) => b.length - a.length);
+            this.foreign = {
+                lots,
+                ids: new Set(ids),
+                tasks: new Set(lots.flatMap((l) => l.tasks.map((t) => `${l.id}/${t.id}`))),
+                refs: ids.length
+                    ? new RegExp(`(?<![\\w/.-])(${ids.map(escapeRe).join('|')})(?:/([\\w-]+(?:\\.[\\w-]+)*))?(?![\\w-]|\\.\\w)`, 'g')
+                    : null,
+            };
+        }
+        return this.foreign;
+    }
     /** Date d'activation de la revue UX obligatoire des lots visibles ; absente = règle inactive. */
     get uxSince() {
         const v = this.doc.get('uxSince');
@@ -86,27 +162,53 @@ export class Plan {
     }
     /** Active la revue UX ; false si elle l'était déjà. */
     enableUx(today) {
-        if (this.uxSince)
+        return this.enableGate('uxSince', today);
+    }
+    recordUx(lotId, verdict, today) {
+        this.recordVerdict('ux', 'la revue UX', lotId, { date: today, verdict });
+    }
+    /** Date d'activation de la revue de code obligatoire des lots à commits ; absente = règle inactive. */
+    get reviewSince() {
+        const v = this.doc.get('reviewSince');
+        return v == null ? undefined : String(v);
+    }
+    /** Active la revue de code ; false si elle l'était déjà. */
+    enableReview(today) {
+        return this.enableGate('reviewSince', today);
+    }
+    /** `commit` : sha du dernier commit compté du lot (le plan ne lit pas git), null s'il n'en a aucun. */
+    recordReview(lotId, verdict, today, commit) {
+        this.recordVerdict('review', 'la revue de code', lotId, { date: today, verdict, commit });
+    }
+    enableGate(key, today) {
+        this.writable();
+        if (this[key])
             return false;
-        this.doc.set('uxSince', today);
+        this.doc.set(key, today);
         // Placer la clé avant « lots » pour garder les réglages groupés en tête.
         const map = this.doc.contents;
-        const idx = map.items.findIndex((p) => String(p.key?.value ?? p.key) === 'uxSince');
+        const idx = map.items.findIndex((p) => String(p.key?.value ?? p.key) === key);
         const lotsIdx = map.items.findIndex((p) => String(p.key?.value ?? p.key) === 'lots');
         if (idx > lotsIdx && lotsIdx >= 0)
             map.items.splice(lotsIdx, 0, ...map.items.splice(idx, 1));
         return true;
     }
-    recordUx(lotId, verdict, today) {
+    recordVerdict(key, label, lotId, entry) {
+        this.writable();
         if (lotId.includes('/'))
-            throw new RafError('la revue UX se note sur un lot, pas une sous-tâche');
-        const node = this.doc.createNode({ date: today, verdict });
+            throw new RafError(`${label} se note sur un lot, pas une sous-tâche`);
+        // Un verdict vide ouvrirait la porte sans rien dire de la revue.
+        if (entry.verdict.trim() === '')
+            throw new RafError(`verdict vide : ${label} attend son verdict — raf ${key} ${lotId} "verdict"`);
+        const node = this.doc.createNode(entry);
         node.flow = true;
-        this.lotNode(lotId).set('ux', node);
+        this.lotNode(lotId).set(key, node);
     }
     lots() {
+        if (this.settings.format)
+            return this.read().lots;
         const raw = this.doc.get('lots').toJSON();
-        return raw.map(normalizeLot);
+        return raw.map((r) => normalizeLot(r));
     }
     lot(id) {
         const found = this.lots().find((l) => l.id === id);
@@ -129,6 +231,7 @@ export class Plan {
         return node;
     }
     add(title, today, opts = {}) {
+        this.writable();
         const known = new Set(this.lots().map((l) => l.id));
         for (const dep of opts.after ?? [])
             if (!known.has(dep))
@@ -152,6 +255,7 @@ export class Plan {
         return id;
     }
     addTask(lotId, title) {
+        this.writable();
         const lot = this.lotNode(lotId);
         let tasks = lot.get('tasks');
         if (!isSeq(tasks)) {
@@ -166,8 +270,13 @@ export class Plan {
         seq.add(node);
         return `${lotId}/${id}`;
     }
-    /** `ref` is `L3` or `L3/t1`. */
+    /**
+     * `ref` is `L3` or `L3/t1`. `unreviewed` : nombre de commits du lot que sa revue de code ne couvre
+     * pas (le plan ne lit pas git) — tous sans verdict, ceux postérieurs au commit relu sinon ; sans lui,
+     * la revue de code n'est pas exigée.
+     */
     setStatus(ref, status, today, opts = {}) {
+        this.writable();
         const [lotId, taskId] = ref.split('/');
         if (taskId) {
             const task = this.taskNode(lotId, taskId);
@@ -191,6 +300,11 @@ export class Plan {
             if (this.uxSince && lot.visible && !lot.ux && !opts.force) {
                 throw new RafError(`${lotId} est visible : revue UX attendue avant done — raf ux ${lotId} "verdict" (--force pour passer outre)`);
             }
+            if (this.reviewSince && opts.unreviewed && !opts.force) {
+                throw new RafError(lot.review
+                    ? `${lotId} : la revue de code précède ${opts.unreviewed} commit(s) du lot, elle est à refaire — raf review ${lotId} "verdict" (--force pour passer outre)`
+                    : `${lotId} a ${opts.unreviewed} commit(s) : revue de code attendue avant done — raf review ${lotId} "verdict" (--force pour passer outre)`);
+            }
         }
         node.set('status', status);
         if (!lot.started && status !== 'dropped')
@@ -199,6 +313,7 @@ export class Plan {
             node.set('finished', today);
     }
     note(ref, text, today) {
+        this.writable();
         const [lotId, taskId] = ref.split('/');
         const lot = this.lotNode(lotId);
         if (taskId)
@@ -213,9 +328,69 @@ export class Plan {
         notes.add(entry);
     }
 }
-function normalizeLot(raw) {
+/** Lit une liste écrite dans un autre format : champs traduits, entrées à parent repliées en sous-tâches. */
+function foreignLots(raw, format) {
+    const entries = raw.map((r, i) => {
+        if (!r || typeof r !== 'object' || Array.isArray(r))
+            throw new RafError(`entrée n° ${i + 1} du plan : un objet est attendu`);
+        const pick = (field) => {
+            for (const key of format.fields[field] ?? [field])
+                if (r[key] != null)
+                    return r[key];
+            return undefined;
+        };
+        // Un horodatage vaut pour son jour.
+        const day = (field) => {
+            const v = pick(field);
+            return typeof v === 'string' && /^\d{4}-\d{2}-\d{2}T/.test(v) ? v.slice(0, 10) : v;
+        };
+        const id = pick('id');
+        if ((typeof id !== 'string' && typeof id !== 'number') || String(id).trim() === '') {
+            throw new RafError(`entrée n° ${i + 1} du plan : identifiant absent`);
+        }
+        const problems = [];
+        const theirs = pick('status');
+        const mapped = Object.keys(format.statuses).length > 0;
+        if (mapped && theirs != null && !Object.hasOwn(format.statuses, String(theirs))) {
+            problems.push(`état « ${String(theirs)} » sans correspondance (cadence.yaml : plan.statuses)`);
+        }
+        const effort = pick('estimate');
+        if (typeof effort === 'string' && !(effort in format.estimates)) {
+            problems.push(`effort « ${effort} » sans correspondance (cadence.yaml : plan.estimates)`);
+        }
+        const notes = pick('notes');
+        const lot = normalizeLot({
+            id,
+            title: pick('title'),
+            status: mapped ? (Object.hasOwn(format.statuses, String(theirs)) ? format.statuses[String(theirs)] : undefined) : theirs,
+            estimate: typeof effort === 'string' ? format.estimates[effort] : effort,
+            quickwin: pick('quickwin'),
+            visible: pick('visible'),
+            after: pick('after'),
+            created: day('created'),
+            started: day('started'),
+            finished: day('finished'),
+            notes: typeof notes === 'string' ? [{ text: notes }] : notes,
+        }, problems);
+        const parent = pick('parent');
+        return { lot, parent: parent == null ? undefined : String(parent) };
+    });
+    const top = new Map(entries.filter((e) => !e.parent).map((e) => [e.lot.id, e.lot]));
+    const lots = [];
+    for (const { lot, parent } of entries) {
+        const into = parent ? top.get(parent) : undefined;
+        if (into && lot.id.startsWith(`${into.id}/`)) {
+            into.tasks.push({ id: lot.id.slice(into.id.length + 1), title: lot.title, status: lot.status });
+            into.problems.push(...lot.problems.map((p) => `${lot.id} : ${p}`));
+        }
+        else {
+            lots.push(lot);
+        }
+    }
+    return lots;
+}
+function normalizeLot(raw, problems = []) {
     const status = STATUSES.includes(raw.status) ? raw.status : 'todo';
-    const problems = [];
     const asDay = (field) => {
         const v = raw[field];
         if (v == null)
@@ -247,9 +422,18 @@ function normalizeLot(raw) {
                 status: STATUSES.includes(t.status) ? t.status : 'todo',
             }))
             : [],
-        ...(raw.ux && typeof raw.ux === 'object'
-            ? { ux: { date: String(raw.ux.date ?? ''), verdict: String(raw.ux.verdict ?? '') } }
-            : {}),
+        ...(asVerdict(raw.ux) ? { ux: asVerdict(raw.ux) } : {}),
+        ...(asVerdict(raw.review) ? { review: asVerdict(raw.review) } : {}),
         problems,
     };
 }
+function asVerdict(raw) {
+    if (!raw || typeof raw !== 'object')
+        return undefined;
+    const v = raw;
+    const verdict = { date: String(v.date ?? ''), verdict: String(v.verdict ?? '') };
+    // Champ présent mais vide : relu « jusqu'à rien », comme un verdict noté sans commit.
+    if ('commit' in v)
+        verdict.commit = v.commit == null || String(v.commit).trim() === '' ? null : String(v.commit).trim();
+    return verdict;
+}

package/dist/session.js

@@ -1,13 +1,41 @@
-import { audit, exemptPlanOnly, nextUp } from './audit.js';
+import { spawnSync } from 'node:child_process';
+import { audit, exemptPlanOnly, nextUp, planCommits } from './audit.js';
 import { diffDays, maxDay } from './dates.js';
-import { readCommits, repoStatus } from './git.js';
+import { repoStatus } from './git.js';
 import { linkCommits } from './link.js';
 import { lockAlive, readLock, readNext } from './state.js';
+const FACTS_TIMEOUT = 120_000;
+/**
+ * Sortie de la commande du projet, ligne à ligne. Un échec se dit et ne bloque rien : ce sont des
+ * faits en plus, pas une condition de la session.
+ */
+function projectFacts(ctx, since) {
+    if (!ctx.facts)
+        return [];
+    const r = spawnSync('sh', ['-c', ctx.facts], {
+        cwd: ctx.root,
+        env: { ...process.env, CADENCE_SINCE: since, CADENCE_TODAY: ctx.today },
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: FACTS_TIMEOUT,
+        killSignal: 'SIGKILL',
+        maxBuffer: 4 * 1024 * 1024,
+    });
+    const lines = `${r.stdout ?? ''}${r.stderr ?? ''}`.replace(/\s+$/, '').split('\n').filter((l, i, all) => l !== '' || all.length > 1);
+    if (r.error || r.signal)
+        lines.push(`✗ commande interrompue (${r.signal ? `délai de ${FACTS_TIMEOUT / 1000} s dépassé` : r.error.message}) : ${ctx.facts}`);
+    else if (r.status !== 0)
+        lines.push(`✗ commande en échec (code ${r.status})`);
+    return lines;
+}
 const short = (c) => `${c.sha.slice(0, 7)} ${c.subject}`;
 /** Commits de la fenêtre reliés aux lots, sans compter comme « sans lot » ceux qui ne touchent que le plan. */
 function period(ctx, since) {
-    const commits = readCommits(ctx.root, { since });
-    return exemptPlanOnly(linkCommits(ctx.plan.lots(), commits, ctx.plan.prefix), ctx.plan, ctx.root);
+    const commits = planCommits(ctx.plan, ctx.root, { since });
+    const linked = exemptPlanOnly(linkCommits(ctx.plan.lots(), commits, ctx.plan.refs), ctx.plan, ctx.root);
+    // Comme raf check : un commit antérieur à l'adoption du plan n'avait pas à citer de lot.
+    const adopted = ctx.plan.since;
+    return adopted ? { ...linked, orphans: linked.orphans.filter((c) => c.day >= adopted) } : linked;
 }
 function byLotLines(linked) {
     return [...linked.byLot].map(([id, cs]) => {
@@ -54,7 +82,7 @@ function lastActivity(lot, commits) {
 export function sessionStart(ctx, opts) {
     const { plan, out, today } = ctx;
     const lots = plan.lots();
-    const all = linkCommits(lots, readCommits(ctx.root), plan.prefix);
+    const all = linkCommits(lots, planCommits(plan, ctx.root), plan.refs);
     out(`${plan.project} — reprise du ${today}`);
     const next = readNext(ctx.state);
     if (next)
@@ -79,6 +107,7 @@ export function sessionStart(ctx, opts) {
     section(out, `Fait depuis ${opts.since}`, done);
     section(out, 'Écarts (raf check)', audit(plan, ctx.root, ctx.newsDir, today).map((i) => `✗ ${i.message}`));
     section(out, 'Dépôt', [repoLine(ctx.root).line]);
+    section(out, 'Faits propres au projet', projectFacts(ctx, opts.since));
     const proposals = [
         ...doing.map((l) => ({ l, why: 'en cours' })),
         ...ready.map((l) => ({ l, why: l.quickwin ? 'gain rapide prêt' : 'prêt' })),
@@ -96,12 +125,13 @@ export function sessionClose(ctx, opts) {
     }
     section(out, 'Commits de la période', commits.length ? commits : ['(aucun)']);
     const quiet = plan.lots().filter((l) => l.status === 'doing' && !recent.byLot.has(l.id));
-    section(out, 'Lots en cours', quiet.map((l) => `${l.id}  ${l.title} — aucun commit sur la période : raf done ou raf note`));
+    section(out, 'Lots en cours', quiet.map((l) => `${l.id}  ${l.title} — aucun commit sur la période : ${plan.readonly ? "le fermer ou l'annoter avec l'outil du projet" : 'raf done ou raf note'}`));
     const issues = audit(plan, ctx.root, ctx.newsDir, today);
     section(out, 'Écarts (raf check)', issues.map((i) => `✗ ${i.message}`));
     const repo = repoLine(ctx.root);
     const lock = lockStatus(ctx.shared);
     section(out, 'Dépôt', [repo.line, ...(lock ? [lock.line] : [])]);
+    section(out, 'Faits propres au projet', projectFacts(ctx, opts.since));
     const open = issues.length + repo.open + (lock?.live ? 1 : 0);
     out(open === 0 ? '\n✓ prêt à fermer' : `\n✗ pas fermé : ${open} point(s)`);
     return open === 0 ? 0 : 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sylad/cadence",
-  "version": "0.2.0",
+  "version": "0.6.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",
@@ -15,7 +15,8 @@
     "build": "tsc -p tsconfig.build.json",
     "test": "vitest run",
     "typecheck": "tsc --noEmit",
-    "prepare": "npm run build"
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run typecheck && npm test"
   },
   "dependencies": {
     "yaml": "^2.5.0"

package/skills/deliver/SKILL.md

@@ -18,6 +18,28 @@ deliver:
       contains: "${SHORT}"   # the new version is the one being served
 ```
 
+A project that already has its own delivery script declares it instead — cadence then keeps the
+preconditions, the lock, the log and the delivered lots, and the script keeps the CI wait, the deploy
+and its business checks:
+
+```yaml
+deliver:
+  script: ./scripts/ship.sh "$CADENCE_SHORT"
+```
+
+Its arguments go after `--`: `cadence deliver -- api frontend` (`--sha <rev>` to deliver a pushed
+commit other than HEAD). Ask the human (or the project's own
+delivery skill) which arguments this delivery needs; never guess them.
+
+## Where to run
+
+Every `cadence` / `raf` command works on the git repository of the current directory. When the
+session runs from a parent folder that holds several projects (not itself a repository), run each
+command inside the project concerned: `cd <project> && cadence …`. The projects are the sub-folders
+that contain `docs/plan/raf.yaml`, or a `cadence.yaml` with a `plan:` key.
+
+Deliver one project at a time: the one the human names, or ask.
+
 ## Steps
 
 1. Before anything: tests and build green locally, everything committed **and pushed** — the CI can
@@ -28,8 +50,17 @@ deliver:
 3. `cadence deliver`. Exit codes: 0 delivered and verified, 1 a step failed, 2 refused before acting.
 4. On failure: read which step failed and why. Fix the cause, commit, push, deliver again. Never rerun
    blindly, never skip a check to make it pass.
-5. On success: `raf done <id>` for the lots it lists **whose effect you have seen**; if one of them is
+5. On success: `raf done <id>` (or the project's own tool when its plan is read-only) for the lots it lists **whose effect you have seen**; if one of them is
    `visible`, `cadence news build` and deliver the news too.
+6. After a green delivery that changes what a page shows or what it is served (screen, API, data
+   source, configuration of either) — in practice every delivery except docs-, plan- or tests-only
+   ones — have the `qa-reviewer` agent walk the delivered app in a real browser, whether the lot
+   is `visible` or not: give it the repository path, the base URL and the lot id. When the lot
+   touched only the backend, the agent starts with the pages that call the changed endpoints. It
+   checks each page against `docs/qa/expectations.md` — what the user must find there — and
+   reports a page left empty, an error shown, an API call that failed or came back empty: what
+   the checks of `cadence.yaml` do not see. Bring its blocking findings to the human. It is not a
+   gate: the delivery stays done, a finding becomes a new lot.
 
 ## Rules
 

package/skills/lead/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: lead
+description: Lead several cadence projects from a parent folder without loading them into the main context — fan out one subagent per project to gather the facts, agree the priorities with the human, delegate each chosen lot to a subagent with a standard brief, have the work reviewed, re-verify it yourself, then deliver one project at a time. Triggers — "/lead", "pilot all projects", "on pilote tout", "délègue aux sous-agents", start of a multi-project day.
+---
+
+# Lead — decide at the top, work in subagents
+
+The lead session stays small: it reads summaries, decides with the human, delegates, checks and
+delivers. Project files are read and changed by subagents, each with its own context. The projects
+are the sub-folders of the current directory that contain `docs/plan/raf.yaml`, or a `cadence.yaml`
+with a `plan:` key. A project whose `cadence.yaml` maps the fields of a plan kept by its own tool is
+**read-only** for `raf`: it takes part in the tour, and its plan is changed with the project's own
+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.
+- **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** —
+  never by a subagent, never two deliveries in parallel.
+- A subagent cannot ask the human anything. When it hits an ambiguity it stops and reports; the lead
+  brings the question to the human.
+
+## 1. Tour of the projects
+
+For each project, a subagent (read-only) runs `cd <project> && cadence session start` and returns at
+most five lines: lots in progress (silent ones flagged), drift, notes from the last close, the next
+ready lot. Two at a time, in the background.
+
+Then report to the human in a compact table — one row per project — and propose **three** items
+across projects, each with project, lot id and one sentence of justification: finish what is in
+progress, then drift that blocks a delivery, then ready quick wins. **Stop and wait for the priority.**
+
+## 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.
+
+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.
+
+## 3. Check
+
+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,
+   ranked, with what it could not verify and a one-line verdict.
+2. **The lead re-verifies itself**: `git log` shows the commits, the test suite and build pass when
+   run by the lead, `raf check` is clean. A subagent is green on what it *could* test; say plainly
+   what nobody could verify.
+3. Fix or re-delegate what the review found; then record the verdict, `raf review <lot> "…"` with
+   the code reviewer's last line brought up to date (and `raf ux <lot> "…"` for a visible lot, with
+   the UX reviewer's), then `raf done <lot>`. Where the gate is on (`raf review enable`, the
+   human's decision for each repository), `raf done` refuses a lot that has commits and no
+   verdict, or a verdict older than its latest commit: a fix made after the review means a new
+   review of the lot, not an edited verdict. A read-only plan has no gate in `raf` (a `uxSince` or `reviewSince` written in it is
+   ignored): the verdict goes into the project's own tool.
+
+## 4. Delivery
+
+One project at a time, by the lead: push, then the `deliver` skill (`cadence deliver --dry-run`, then
+`cadence deliver`). Follow the human's standing instructions about confirmation before production.
+
+After a green delivery that changes what a page shows or what it is served (screen, API, data
+source, configuration of either) — in practice every delivery except docs-, plan- or tests-only ones
+— have the `qa-reviewer` agent check the delivered app, as a fresh subagent: give it the absolute
+path of the project, the base URL of the delivered app and the lot id. The lot need not be
+`visible`: a backend-only lot can empty a page without changing a screen. When the lot touched only
+the backend, the agent starts with the pages that call the changed endpoints. It walks the pages in
+a real browser against the project's expectations (`docs/qa/expectations.md`: per page, what the
+user must find there) and returns measured findings; it reads only, and never logs in. Bring its
+blocking findings back to the human — a page whose main content is missing, or that shows an error,
+is a defect even when the delivery checks are green — with its proposed follow-up lines. A project
+without an expectations file gets a draft back: show it to the human, who corrects it and decides
+whether it is committed. It is not a gate: `raf done` does not wait for it, and a finding becomes a
+new lot, not a reopened one.
+
+## 5. Close
+
+At the end, the `session-close` routine in each project touched, and `cadence session next` lines in
+each. Give the human one line per project: delivered, in progress, blocked (and why).

package/skills/session-close/SKILL.md

@@ -5,6 +5,16 @@ description: Close a work session on a repository that uses cadence — plan hyg
 
 # Session close — close without memorising everything
 
+## Where to run
+
+Every `cadence` / `raf` command works on the git repository of the current directory. When the
+session runs from a parent folder that holds several projects (not itself a repository), run each
+command inside the project concerned: `cd <project> && cadence …`. The projects are the sub-folders
+that contain `docs/plan/raf.yaml`, or a `cadence.yaml` with a `plan:` key.
+
+With no project named, run `cadence session close` in each project touched during the session
+(`git log --since` or `git status` tell which) and close each one.
+
 ## Steps
 
 1. Run `cadence session close` (over several days: `--since "2 days ago"`). Exit code 1 means
@@ -16,6 +26,10 @@ description: Close a work session on a repository that uses cadence — plan hyg
      is genuinely outside the plan (docs, chores);
    - a finished lot marked `visible` without a news entry → `cadence news new <id>`, written for the
      user, with a screenshot;
+   - a lot that `raf done` refuses, or that the check reports as finished, for lack of a review —
+     code review of a lot with commits, or one older than the lot's latest commit
+     (`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
    NOT already say — a trap and its cause, a decision or correction from the human, a collaboration
@@ -23,6 +37,9 @@ description: Close a work session on a repository that uses cadence — plan hyg
 4. **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,
    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.