@sylad/cadence 1.9.0 → 1.11.0

package/docs/ref.md

@@ -7,7 +7,7 @@ tables drawn as pictures, message templates, figures of a norm (WMO, ICAO…). `
 turns such a document into files a session can read without losing the pictures. The whole
 design is in
 [`docs/superpowers/specs/2026-10-23-ref-documents-de-reference-design.md`](superpowers/specs/2026-10-23-ref-documents-de-reference-design.md)
-(issue #14); this page describes what is delivered so far: **`cadence ref add`** (lot 1 of 10), **`cadence ref measure`** (lot 2 of 10) **`cadence ref check`** with the inventory schema (lot 3 of 10), and **`cadence ref eval`** (lot 4 of 10, with the synthetic corpus `cadence ref corpus`).
+(issue #14); this page describes what is delivered so far: **`cadence ref add`** (lot 1 of 10), **`cadence ref measure`** (lot 2 of 10) **`cadence ref check`** with the inventory schema (lot 3 of 10), **`cadence ref eval`** (lot 4 of 10, with the synthetic corpus `cadence ref corpus`) **`cadence ref analyse`** (lot 5 of 10: the `reference-analyst` agent, one single reading) and **`cadence ref diff`** with the double reading (lot 6 of 10). **The series stops at lot 6**: the stopping point of the double reading (hypothesis H1) was not met, so lots 7 to 10 are dropped and the double reading stays an option, `--double` ([measurement and conclusion](mesures/ref-double-lecture-2026-10-25.md)).
 
 ## `cadence ref add <document.pdf> [--sections 3-5,9] [--slug name]`
 
@@ -35,7 +35,7 @@ Registers a PDF and builds, for it:
   the first on a page that holds an image wins, then the first with a separator, then the first. Each entry has its page, line, box, its images, and **the passages that cite it** (page,
   line, exact line; `nommee` when the text names the figure, `designee` for « as shown
   below » / « ci-dessous », attached to the nearest caption of the page). Plurals count one citation per figure
-  (`Figures 2 and 3`, `Tables 4 to 6`, `Figs. 2.1 et 2.2`); a number keeps the letters of an annex numbering (`Figure 1.B.1`, `Table 12.B.3`). Listed under **`unresolved`**
+  (`Figures 2 and 3`, `Tables 4 to 6`, `Figs. 2.1 et 2.2`), and ranges are expanded figure by figure (`Figures 2–4` with an en dash glued to its bounds — a dash set off by spaces or an em dash, `Figures 2 and 3 — 10 stations`, `Figures 2 and 3—10 stations`, is prose and not a range —, `Figures 01–03` keeping the leading zeros of its bounds, `Figures 2, 4 to 6`, `Figures 1.1 to 1.3`, `Figures 1.B.1 to 1.B.3`, `Figures 3-1 to 3-3`, `Tables A1 to A3`; a range of which the bounds do not share their prefix, that decreases or that spans 50 numbers or more keeps its two bounds, and a bare second bound after a prefixed one (`Tables 4.8–10`, `A3–1`) is not a figure of its own; the figures in the middle of a range are cited when they have a caption, and are never an unresolved link when they have none, so `figures 11–20` leaves only `Figure 11` and `Figure 20` to resolve, and an explicit `Figure 15` further on the same line stays cited or unresolved on its own); a number keeps the letters of an annex numbering (`Figure 1.B.1`, `Table 12.B.3`). A figure preceded by the word `code` or `indicator` (`code figure 3`, `code figures 2 and 3`, `indicator figures 1 to 6, 8 and 9` — a value of a WMO code —, including when the word ends the previous line, or the last line of the previous page before its footer and the header of the next page, and the reference opens the next one) is not a citation and not an unresolved link; neither is an en-dash range (`figures 20–49`) in a sentence that already has a `code figure` (`code figure 17 shall have precedence over figures 20–49`). A header or footer is a line that, digits apart, opens or ends three pages or more. `code table` is not affected. Listed under **`unresolved`**
   (« lien non résolu »): a citation of a figure with no caption, a figure that nothing cites,
   and an image on a page that has no caption (`image sans légende`).
 
@@ -205,7 +205,10 @@ ref : outil absent du PATH, à installer (rien n'est installé d'office) :
 (`poppler-utils`, `imagemagick`, `tesseract-ocr`.) `add` does not call ImageMagick or tesseract, `measure` calls tesseract (and only for the text); both check all the tools at the first call, as the design asks.
 ImageMagick is not called by either: `measure` decodes the rendered PNG pages itself. The rest of cadence depends on none of them.
 
-Exit codes: 0 done, 2 refusal (tool, file, option, slug, folder).
+A poppler tool that fails while `add` reads the document (`pdftotext`, `pdftoppm`, `pdfimages`, `pdftohtml`: non-zero exit, output too large, disk full)
+is a refusal too, naming the tool, the document and the reason: `ref : pdftotext a échoué sur doc.pdf (disque plein)`. The folder of a new document is not left behind (an existing document keeps its `document.json`; `pdftohtml` is read before anything is written).
+
+Exit codes: 0 done, 2 refusal (tool, file, option, slug, folder, tool failure).
 
 ## `cadence ref eval <attendu> <lecture> [--json]`
 
@@ -273,6 +276,102 @@ A reading whose `document.slug` or `document.sha256` differs from the expected o
 mixed). Exit codes: **0** done, **2** refusal (wrong call, file absent or unreadable, invalid reading, other document, folder with
 no `attendu.json`). `--json` prints one object: `total`, `types`, `pieges`, `tokens`, `cas`.
 
+## `cadence ref diff <lecture-a.json> <lecture-b.json> [--out inventaire.json] [--seuil 30]`
+
+Reconciles **two readings of the same document** (design §3, step 3), by program, without any session. Both files must pass `ref check`, be of genre `lecture`, and carry the same `slug` **and** `sha256` (a reconciliation over two
+versions of a document is refused, exit 2). Elements are paired **by type, page, identity and zone overlap**; the identity is what designates an element whatever its id, zone and confidence (the same notion as `ref eval`: the
+text of a `texte`, role and content of a `composant`, figure of a `lien`…), since two independent readings number their ids their own way:
+
+| Paired as | When | Result |
+|---|---|---|
+| **concordant** | same identity and same affirmation (the role of a text, the verdict of a link, the cells of a table…) | one element, `mesure` if either reading measured it, else `lu`; a doubt of one reading (`incertain`) stays a doubt, with its cause |
+| **divergent** | same identity but another affirmation, or another identity on the same zone (overlap ≥ 50 %, same type and page: `120 KT` read `120 kt`) | one `incertain` element whose cause holds both versions: `lectures divergentes — libelle : A « 120 KT » ≠ B « 120 kt »`; neither is chosen |
+| **seul** | carried by one reading only | `incertain` (`lu dans la lecture B seulement, troisième regard non fait`) until the third look rules on it (see `ref analyse`) |
+| **silence** | a question, in either reading | gathered (one question once), never sent to a third look and not counted below: a silence is not a reading that someone else contradicts |
+
+More than **30 %** of the paired-or-single elements unpaired (silences left out, `--seuil` changes it, in percent) means the two readings do not describe the same document: no reconciliation, the question goes to the lead (exit 1, nothing written).
+The ids of the result are renumbered `<slug>#<type>-<n>` (reading A in its order, then what B alone carries) and the references (`composant.ecran`, `etat.cible`, `statut.couvre`) follow; an element that referred to a discarded one is discarded with it, **except a paired element** (both readings carry it): it holds while one of its two versions points to a kept element, and is then `incertain` with the cause when only one version does; it is discarded only when both versions point to discarded elements (see `ref analyse`, « Reconciliation »).
+
+```
+$ cadence ref diff a.json b.json --out inventaire.json
+concordants : 31 · divergents : 2 · seuls : 3 (A : 1, B : 2) · silences : 9
+non appariés : 8.3 % (seuil 30 %)
+divergent : texte p.2 : libelle : A « 120 KT » ≠ B « 120 kt »
+seul (B) : composant p.1 : bouton|Layers
+```
+
+`--out` writes the reconciled inventory (genre `inventaire`, valid for `ref check`). Exit codes: **0** reconciled, **1** too many unpaired elements, **2** refusal (wrong call, unreadable or invalid file, not a reading, two documents, bad `--seuil`).
+
+## `cadence ref analyse <document.pdf> [--sections 3-5,9] [--slug name] [--model sonnet|opus|haiku] [--model-b sonnet|opus|haiku] [--seuil 30] [--double]`
+
+The chain: `add`, then **one reading** (one session of the [`reference-analyst`](../agents/reference-analyst.md) agent, `lectures/a.json`), checked by the program. `--double` adds the **double reading** of the design (§3): two independent readings, `ref diff` by program,
+a **third look** at what only one reading carries, and the reconciled inventory.
+
+**The double reading is an option, not the default, because its measurement did not show a gain.** On the synthetic corpus (7 cases, one draw per case) it gives the same recall as the single reading (83 %), a **higher** rate of false « read » (50.7 % against 37.7 % for reading A alone), the same
+three misses and **2.8 times the tokens** (63 250 per page against 22 375), with errors that are correlated between the two readings (hypothesis H1 not met). The design is explicit: a version that raises the rate of false « read » or lowers the recall of the `precise` links does not ship as the default.
+`--model-b` and `--seuil` are accepted with `--double` only (exit 2 otherwise). The figures and their limits: [`docs/mesures/ref-double-lecture-2026-10-25.md`](mesures/ref-double-lecture-2026-10-25.md) (« Lecture des chiffres », conclusion at the end).
+
+**Single reading (default).** One fresh session of `reference-analyst`, on `--model` (default `sonnet`), writes `lectures/a.json`; the program reads the file itself (below). The `lectures/b.json` and `inventaire.json` of an earlier `--double` pass are removed first: they would not match the new `a.json`.
+
+**Two readings (`--double`).** Two fresh sessions of the [`reference-analyst`](../agents/reference-analyst.md) agent (`claude -p`, the review effort and the permission mode of `orchestrate` in `cadence.yaml`, a working directory that is the
+document folder) run together: reading **A** on `--model` (default `sonnet`), reading **B** on `--model-b` (default `opus`: another model decorrelates the errors, hypothesis H1). Each agent looks at every rendered page whole,
+then every zone at full resolution, measures with `cadence ref measure`, copies every text verbatim, links every figure to the passages that cite it (`confirme`, `precise`, `contredit`), writes what the document does not show as a `silence`,
+marks `incertain` (with its cause) what it cannot read for sure, and writes **`<references.dir>/<slug>/lectures/a.json`** (resp. `b.json`): a reading (`genre: "lecture"`) in the format of
+[`templates/inventaire.json`](../templates/inventaire.json), validated by `cadence ref check` before it hands back. The two briefs are the same text, the file to write apart; neither names the other reading, an expected inventory or a corpus,
+and the agent is told never to open another file of `lectures/`. The sessions need `claude` on the `PATH` (or `CADENCE_CLAUDE_BIN`) and the system tools of `ref add`.
+
+**The program does not trust the reports.** For each reading it reads the file itself: it must exist (the ones of an earlier run, `a.json`, `b.json` and `inventaire.json`, are removed before the sessions start), pass `ref check`, be a `lecture`
+and carry the `slug` and `sha256` of the document that was read, never another (a reading of two versions mixed is refused). It then writes **`usage`** into each reading, `{ tokens, modele, session }`, `tokens` being the input, cache-write
+and output tokens of the session (the count of the orchestrate budget; cache reads are left out), which the agent never writes.
+
+**Reconciliation.** [`ref diff`](#cadence-ref-diff-lecture-ajson-lecture-bjson---out-inventairejson---seuil-30) pairs the two readings. More than 30 % of unpaired elements (`--seuil`, in percent): no reconciliation, exit 1, the question to the lead
+(the two readings stay in `lectures/`, `cadence ref diff` compares them again). Otherwise:
+
+- **concordant** elements become one `lu` (or `mesure`) element; **divergent** ones are `incertain` with both versions in the cause, **never chosen**;
+- the elements **only one reading carries** go to the **third look**: one session of the [`reference-verifier`](../agents/reference-verifier.md) agent (read-only: `Read` and `Bash` to measure; same model as reading A) that sees **only those elements**, each with the
+  rendered page and a **crop** of its zone (`crops/regard-<n>.png`, the zone and 24 px around it; no crop when the page is not rendered, the brief then says so), and answers `confirme` or `ecarte` with a reason. **Confirmed**: the element keeps its confidence
+  (`mesure` stays `mesure`, `lu` stays `lu`, a doubt stays a doubt); **discarded**: it disappears, with what only held through it (a state of a discarded component, a badge that covers nothing any more). A paired element (both readings carry it) holds as long as **one** of its two versions points to kept elements: when only one version pointed to a discarded element (a reading that cut a second screen wrongly and attached its components to it), the element stays, attached as the other version has it, and is `incertain` with the cause (`rattachement : la lecture A le rattachait à un élément écarté…`); it disappears only when both versions point to discarded elements. A verdict without a reason, an unknown verdict or a number that is not
+  in the list counts as **no answer**: the element stays `incertain` (`troisième regard sans réponse`), never a `lu` by default. No element carried by one reading only: no third look, no session;
+- the **silences** of both readings are gathered, once per question, and never sent to a third look.
+
+The result is **`<references.dir>/<slug>/inventaire.json`**: `genre: "inventaire"`, valid for `ref check`, ids renumbered, `usage` = `{ tokens, lectures: { a, b, regard } }` (the total of the three sessions and each one's tokens and model, what `ref eval` reads for the tokens per page)
+and `reconciliation` = the counts, the unpaired ratio and, for each element the third look ruled on, `{ lecture, id (in its reading), verdict, raison }`.
+
+A session cut by a signal with nothing written is started again once in a fresh session (like a review); cut twice, it is a failure (exit 2). Without `--double` the single reading is written to `lectures/a.json` and checked as above; `--model-b` and `--seuil` are refused then (exit 2).
+
+**Declared ceiling: 20 pages per reading** (`LECTURE_PAGES_MAX`, design §5 « Taille »). With `--sections`, the pages read are those of `--sections` plus the pages of the figures they cite: the pages an
+earlier `add` of the same document rendered stay on disk but are **not** read, so choosing fewer pages with `--sections` works under the same slug. Without `--sections`, every rendered page is read (the whole document when it
+has 30 pages or fewer, else the pages an earlier `add` rendered). More than 20 pages to read is refused before any session (exit 2, the count and the command `cadence ref analyse <document> --slug <slug> --sections 3-12`), and so is a large document with no
+`--sections` and no page rendered. Splitting into several pairs of readings is not done here.
+
+A session cut by a signal and started again is counted in full: its tokens (read back from its Claude Code journal, as `orchestrate` does) are added to those of the fresh one, and the half-written reading of the cut session is removed before the fresh one starts.
+
+```
+$ cadence ref analyse norme.pdf --sections 4-9 --double
+norme : norme.pdf
+pages : 120
+rendues : 8 (4, 5, 6, 7, 8, 9, 33, 34)
+…
+norme : double lecture (A sonnet, B opus) — 8 pages lues (plafond d'une lecture : 20)
+lectures : ~/.local/share/cadence/references/norme/lectures/a.json, ~/.local/share/cadence/references/norme/lectures/b.json
+réconciliation : concordants 31 · divergents 2 · seuls 3 · silences 9 — non appariés 8.3 % (seuil 30 %)
+troisième regard (sonnet) : 2 confirmés, 1 écarté, 0 sans réponse
+inventaire : ~/.local/share/cadence/references/norme/inventaire.json
+éléments : 44 (mesure : 6, lu : 27, incertain : 11)
+tokens : 520000 (65000 par page, 8 pages lues) — A : 190000, B : 250000, troisième regard : 80000
+question : Que veut dire « Figure 1 » ?
+```
+
+The last lines are one `question :` per distinct question of the agents (a `contredit`, an `incertain`). Exit codes: **0** done, **1** a refused reading (no file, `ref check` deviations, wrong genre, wrong document: one
+`✗ lecture A : <reason>` line per deviation then `N écart(s)` on the standard output, the file is left as written, no `usage` is added) or too many unpaired elements, or the third look discarding every element (all of them were carried by one reading only: nothing is left to write, no inventory, the readings stay, a question to the lead), **2** refusal (unknown `--model` or `--model-b`, no page or more than 20 to read, tool or file as for `add`, a session that
+failed: `la session de lecture a échoué : <cause>`), **3** quota reached (message on the error output, no inventory; the readings already written stay; run it again later). The tokens per page of the output divide by the pages **read**; `ref eval` divides by the `pages` of the expected inventory,
+the same number for a corpus case read whole. Without `--double` the output is the one of lot 5: `<slug> : lecture unique (<model>) — …`, `lecture : <file>`, `éléments : …`, `tokens : …`.
+
+### Reference measure on the corpus
+
+`docs/mesures/ref-lecture-unique-2026-10-24.md` states what the single reading is measured on and with which commands (recall, false « read », tokens per page against the corpus of `ref corpus`, the declared ceiling), and what was measured.
+The double reading is measured the same way, `ref eval` on `inventaire.json` instead of `lectures/a.json`, and compared with that baseline: `docs/mesures/ref-double-lecture-2026-10-25.md` (hypothesis H1, the stopping point of lot 6: not met, which is why `--double` is an option).
+
 ## `cadence ref corpus <dossier> [--sans-rendu]`
 
 Writes the **synthetic corpus with a known truth** that `ref eval` scores against (design §« Évaluation »): seven small documents,

package/docs/releasing.md

@@ -7,11 +7,11 @@ A version exists in three places and is published in two; a release does all of
 1. Bump `version` in `package.json` (then `npm install` to refresh `package-lock.json`),
    `.claude-plugin/plugin.json` and `.claude-plugin/marketplace.json`, and write the version's section of
    `CHANGELOG.md` (`## [x.y.z] - date`, what changes for the user, lots cited), in **one commit that holds
-   only those files** (the version fields and the CHANGELOG, nothing else in the manifests, the « What's new »
-   section of the README, the one place of it a release rewrites, and `docs/whats-new.md`, its long form: add the version there too). Such a commit is
+   only those files** (the version fields and the CHANGELOG, nothing else in the manifests, `docs/whats-new.md`: add the version to its « In two lines » list and its
+   long form (the README no longer carries a « What's new » section, L326)). Such a commit is
    exempt from the code-review gate like a plan commit: it closes the lot after its review, and `raf check`
    does not ask for a new one (nor does it count it as a commit without a lot). The « What's new »
-   summary is ordered by version, a number known only at the release and shared by several lots: write it
+   summary (`docs/whats-new.md`) is ordered by version, a number known only at the release and shared by several lots: write it
    in that commit, not before the review. A commit that touches any other file
    — or another field of a manifest, or a dependency in `package-lock.json` — is work like any other and has
    to be reviewed.

package/docs/skills.md

@@ -10,7 +10,7 @@ As a plugin:
 ```
 
 gives `/cadence:session-start`, `/cadence:session-close`, `/cadence:deliver`,
-`/cadence:lead` and the `ux-reviewer`, `code-reviewer` and `qa-reviewer` agents. Or copy them into the
+`/cadence:lead`, `/cadence:orchestrate` and the `ux-reviewer`, `code-reviewer` and `qa-reviewer` agents. Or copy them into the
 repository with `cadence skills install` (to `.claude/skills/cadence-*` and
 `.claude/agents/cadence-*.md`; `--dir` for another `.claude` folder,
 `--force` to overwrite local edits).
@@ -43,6 +43,7 @@ repository with `cadence skills install` (to `.claude/skills/cadence-*` and
   subagents as the session cap at most (2 by default, `CADENCE_MAX_SESSIONS`), the ones it starts by hand declared with `cadence lead hold`, never two in the same repository. The whole flow is drawn in
   [docs/lead.md](lead.md); how a lot, a wave, the lead and the service of cadence itself fit together, in four figures, is in
   [docs/fonctionnement.md](fonctionnement.md).
+- **orchestrate**: the command line of a wave without going through `lead` — `cadence orchestrate <project>:<lot>[@<model>]` (a lot id with « / » kept as is, no `--lot` or `--model` option) and the resume with `--resume [--wave <wave>]`; the description triggers on « lancer une vague orchestrate ».
 - **ux-reviewer** (agent): captures at 1440 and 390 px, findings grounded in a
   named rule (Nielsen, WCAG 2.2 AA) or a measurement, ranked, turned into
   `raf add --parent` sub-tasks, and a one-line verdict for `raf ux`. It never
@@ -65,6 +66,18 @@ repository with `cadence skills install` (to `.claude/skills/cadence-*` and
   document behind the lot; the lead calls it by hand. A document outside the repository only when the project's
   `cadence.yaml` names it (`docs.articles`): the agent then proposes a lot for that repository's plan and never writes it
   ([news](news.md#the-librarian-doc-keeper)).
+- **reference-analyst** (agent, L265): given the folder of a document registered by `cadence ref add` and the file to
+  write, it looks at every rendered page whole, then every zone at full resolution, measures with `cadence ref measure`
+  (never by eye), copies every text verbatim, links each figure to the passages that cite it and writes one reading in
+  the format of `templates/inventaire.json`, validated by `cadence ref check`; what it cannot read for sure is
+  `incertain` with its cause, what the document does not show is a `silence`. Its tools are `Read`, `Write`, `Bash`,
+  `Grep`, `Glob`: it writes only its reading, never the tokens (the program counts them), never an expected inventory, and it never opens
+  another file of `lectures/` (L266: with `--double`, `cadence ref analyse` launches it twice, readings A and B, which must stay independent).
+  `cadence ref analyse` launches it ([ref](ref.md#cadence-ref-analyse-documentpdf---sections-3-59---slug-name---model-sonnetopushaiku---model-b-sonnetopushaiku---seuil-30---double)).
+- **reference-verifier** (agent, L266): the third look of `cadence ref analyse`. It receives only the elements that one of the two readings wrote and the
+  other did not, each with the rendered page and a crop of its zone, and answers `confirme` or `ecarte` with a reason, measuring with
+  `cadence ref measure` rather than by eye and never guessing (what it cannot tell is `ecarte`). Its tools are `Read` and `Bash`: it writes nothing and never sees the readings
+  ([ref](ref.md#cadence-ref-analyse-documentpdf---sections-3-59---slug-name---model-sonnetopushaiku---model-b-sonnetopushaiku---seuil-30---double)).
 - **qa-reviewer** (agent): any web app (read-only like `ux-reviewer`: same tool list, no `Edit`, no `Write`); given a repository and a base URL (and
   optionally a lot id, to walk only the pages it touched — those that call the
   changed endpoints, those of the screens it changed, the pages that consume the services the lot changed,

package/docs/spec.md

@@ -26,7 +26,7 @@
 
 `cadence spec check` prints the same summary line for each kind (`N cas, N règles (N hypothèses), N contrats, N données` for a back-end sheet) and keeps its exit codes: 0 valid, 1 violations, 2 usage.
 
-`cadence spec reseal <lot> <test> --reason texte` is the lead's way to correct one sealed acceptance test of the lot in progress that contradicts its sheet (unchanged, or amended by commits of the lot, L217; of a delivered lot, also by commits of another delivered lot, L229) (of a delivered lot: add `--porteur <lot in progress>`); refused while a wave of the repository is running, or a wave that is not `done` keeps open (question waiting, suspended, queued) any lot of this repository still `doing` in its plan, the resealed lot or another (L238: one error, also when a live wave holds the lock, names each wave (live ones to wait for), its launch folder and, for each stopped wave, the single `cd <folder> && cadence orchestrate --resume <wave> --drop <project>:<lot> --drop …` that closes all its open lots of the repository, the queued ones that are not `doing` in the plan included (L239); a lot `done` or absent in the plan never refuses), see [The accept step](orchestrate.md#the-accept-step-red-acceptance-tests-and-their-lock).
+`cadence spec reseal <lot> <test> --reason texte` is the lead's way to correct one sealed acceptance test of the lot in progress that contradicts its sheet (unchanged, or amended by commits of the lot, L217; of a delivered lot, also by commits of another delivered lot, L229) (of a delivered lot: add `--porteur <lot in progress>`); refused while a wave of the repository is running, or a wave that is not `done` keeps open (question waiting, suspended, queued) any lot of this repository still `doing` in its plan, the resealed lot or another (L238: one error, also when a live wave holds the lock, names each wave (live ones to wait for), its launch folder and, for each stopped wave, the single `cd <folder> && cadence orchestrate --resume --wave <wave> --drop <project>:<lot> --drop …` that closes all its open lots of the repository, the queued ones that are not `doing` in the plan included (L239); a lot `done` or absent in the plan never refuses), see [The accept step](orchestrate.md#the-accept-step-red-acceptance-tests-and-their-lock).
 
 `cadence spec qa <fiche.yaml>` derives from a valid sheet the section of `docs/qa/expectations.md` for its screen and prints it on the standard output
 (it never writes the file: you paste the section, and the lead commits it like the rest of the plan files). A sheet with violations prints them on the

package/docs/whats-new.md

@@ -2,7 +2,37 @@
 
 # What's new, version by version
 
-The long form of the README's « What's new » (the README keeps two lines per version). The full history, with the date of each version, is in [CHANGELOG.md](../CHANGELOG.md).
+## In two lines
+
+- **1.11.0**: a new `orchestrate` skill gives the command line of a wave without `/lead`; the `deliver` skill says how to deliver a commit that is not `HEAD` (push that sha alone first, never forced).
+- **1.10.0**: the worktree mode of `cadence orchestrate` needs only the `orchestrate.worktrees` key and is on for cadence itself; the gate plays `orchestrate.build` before the tests, and `lead tour` flags a missing `orchestrate.test`.
+  A lot waiting for a slot obeys `--drop` and `--stop-after-current`, the pre-check is back on Sonnet, `cadence perf` classes red deliveries, and the README is a short home page again.
+- **1.9.0**: the plan lives at `.cadence/raf.yaml` (`raf migrate`); `cadence ref` reads reference documents; `doc-keeper` agent, `orchestrate.testGate`, `cadence lead hold` shown by `cadence-hud`.
+- **1.8.0**: `cadence perf` shows the speed of the workflow next to its quality (cost in euros per delivered lot, red deliveries, blocking QA findings), and `cadence lead tour` opens with a perf header.
+- **1.7.0**: `cadence orchestrate` no longer replays `accept` on a green sealed acceptation and refuses `--resume --dry-run`; `spec reseal --porteur` accepts a sheet amended by a delivered lot; the README becomes a short home page.
+- **1.6.0**: the mockup review sweeps everything in its first report and runs up to `orchestrate.maquetteReviews` times (3 by default); the acceptance lock names the first offending commit.
+- **1.5.1**: publishes 1.5.0 (tagged, never published): one UX review per lot, replay of a lot handed back for its budget, a self-check list in the briefs, a `tests.yml` workflow.
+- **1.5.0**: `gate: { count: N, … }` makes a lot wait for N done lots of a kind; `raf todo <id>` puts a started lot without work commits back to `todo`.
+- **1.4.0**: `cadence spec reseal` accepts a sheet amended by the lot's commits; wave budgets recalibrated; a `git checkout` in a session no longer stops the wave.
+- **1.3.0**: the spec step narrows to `screen: page`; `cadence spec reseal … --porteur` re-seals an unstable test; `cadence orchestrate --waits`; a third correction pass when the review converges.
+- **1.2.0**: the spec step reaches lots without a screen (`spec: true`), `orchestrate.accept` may be a list of runners, `lead.ux: lead`, and the code in service is a separate worktree.
+- **1.1.0**: the spec step of `cadence orchestrate`: screen sheet, reviewed mockup, red locked acceptance tests, and briefs that carry rule → test → green.
+- **1.0.0**: the first major release, a stable contract that follows semantic versioning; the [stability page](stabilite.md) lists what is guaranteed.
+
+<details>
+<summary>Older versions (0.10.0 to 0.28.0)</summary>
+
+Each is a paragraph in [docs/whats-new.md](whats-new.md) and a full section in [CHANGELOG.md](../CHANGELOG.md): `cadence-hud` (0.12.0 to 0.25.0), `cadence orchestrate --continue` and `--status --watch`, `cadence lead tour`, `hook.autostart`, `docs.sync` and `docs.articles`, neighbouring repositories, `raf ignore`.
+
+</details>
+
+## Version by version
+
+The long form of « In two lines » above (the README no longer carries a « What's new » section since L326: it links here). The full history, with the date of each version, is in [CHANGELOG.md](../CHANGELOG.md).
+
+**1.11.0**: the plugin eval of 1.10.0 found two gaps in the skills, both closed and replayed at 1.00. A new `orchestrate` skill (L335, `docs/skills.md`) carries the command line of `cadence orchestrate` — `<project>:<lot>[@<model>]`, a lot id with « / » kept as is, `--resume` with or without `--wave` — so that an agent reaches it without `/lead` instead of inventing `--lot` and `--model`. The `deliver` skill (L334, `docs/deliver.md`) says how to deliver a commit that is not `HEAD`: push that sha alone (`git push origin <sha>:main`), then `cadence deliver --dry-run --sha <sha>` and `cadence deliver --sha <sha>`, because with `ci: github` the wait is for the run of that exact sha and GitHub only builds the tip of a push; skip the push when the sha is already on a remote branch, and never force a push refused as non-fast-forward.
+
+**1.10.0**: the worktree mode of `cadence orchestrate` (one git worktree per lot, independent lots of one repository in parallel) is no longer behind `CADENCE_EXPERIMENTAL_WORKTREES=1`: the `orchestrate.worktrees` key alone is the switch, on start and on `--resume`, `--integrate`, `--replay` and `--continue`, and cadence's own `cadence.yaml` turns it on after the trials L310 and L316 (L320); a red at the integrated tip is played once more before the lot is handed back, and the refusal names the red tests (L328); a union of the `CHANGELOG.md` entries of parallel lots, which accepts that a lot rewrites its own entry (L314, L323), and a kept branch recovered without the pre-check (L311). The gate of the wave plays `orchestrate.build` before `orchestrate.test`, a red build handing the lot back as a « build » finding (L333); `cadence lead tour` and `cadence orchestrate --dry-run` flag a project without `orchestrate.test` and name the probable command (L327). The pre-check is back on Sonnet in cadence's own configuration after the local model failed on about one lot in three, skips a lot created after the last code commit of the repository, and `cadence perf` measures it per lot (L322, L328). A lot waiting for a session slot obeys `--drop` and `--stop-after-current` (L332); `--resume` without a wave resumes the only unfinished one and is refused when several are (L309). `cadence perf` classes the red deliveries written before the class from their text (L331) and names the step that carries a rise of the tokens per lot (L312). `npm run service` purges the old copies put in service (L330), `cadence deliver` keeps a Ctrl-C (L325, L329), and `raf docs-ok` acknowledges a `docs.sync` gap (L317); `raf check` no longer reports two false drifts (L321). `cadence ref analyse` reads a reference document, `cadence ref diff` reconciles two readings and `--double` reads twice, an option (L265, L266); `cadence ref add` cites a range of figures and no longer reads « code figure n » as a citation (L274, L313); a failing PDF tool is a refusal, not a stack trace (L275). The README is a short home page again, the detail having moved to `docs/overview.md` (L326). Details: [CHANGELOG.md](../CHANGELOG.md).
 
 **1.9.0**: the default plan is `.cadence/raf.yaml`, a hidden folder git versions and `docs/` never publishes (L246), and `raf migrate [--dry-run]` moves a legacy plan and the readers of the old path (L284, L305); `raf title`, `raf visible`, `uses:` resources shown by `lead tour` and the lot `goal:` (L244, L273, L251–L253, L258). `cadence ref add|measure|check|corpus|eval` registers reference documents outside the repository, measures a rendered zone, validates the inventory schema and scores a reading against a known truth (L261–L264). In `cadence orchestrate`: the `doc-keeper` agent and `docs.articles` (L306, L308), the mechanical `orchestrate.testGate` before the review (L287), `precheck: local` on every lot with no commit (L296), a write-step time limit proportioned to the lot (L298), sessions that no longer hold their slot after their report (L285), the real weekly-limit message recognised (L286), and an experimental worktree mode with `--resume --integrate|--replay` and `--remove-worktree` (L279, L299–L304). `cadence lead hold|release` counts the lead's hand-started sessions, an expired one is flagged by `lead tour`, `--status` and the `cadence-hud` band (0.5.0; L255, L276, L278). `cadence deliver --sha` is accepted while a wave runs (L277), `CADENCE_DEPLOYED_FILE` names the deployed sha (L277, L281) and `deliveries-failed.log` keeps the class and last lines of a red delivery, secrets masked (L282, L289, L294). `cadence perf` breaks red deliveries down and counts the `review-small` UX (L282, L283). Details: [CHANGELOG.md](../CHANGELOG.md).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sylad/cadence",
-  "version": "1.9.0",
+  "version": "1.11.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/deliver/SKILL.md

@@ -32,10 +32,33 @@ writes that sha into the file named by `$CADENCE_DEPLOYED_FILE`: cadence logs it
 (a content that is not a hexadecimal commit sha — `HEAD` or a branch name included — fails the delivery; empty during a wave, the log keeps `$CADENCE_SHA` and a warning
 says the head moved).
 
-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
+Its arguments go after `--`: `cadence deliver -- api frontend` (`--sha <rev>` to deliver a commit
+other than HEAD, see « Delivering a commit that is not HEAD »). Ask the human (or the project's own
 delivery skill) which arguments this delivery needs; never guess them.
 
+## Delivering a commit that is not HEAD
+
+When HEAD holds work that must not ship and an earlier commit must, push **that sha alone** first,
+then deliver it:
+
+```sh
+git push origin <sha>:main
+cadence deliver --dry-run --sha <sha>
+cadence deliver --sha <sha>
+```
+
+The order matters. With `ci: github`, cadence waits for the run of that exact sha, and GitHub only
+builds the tip of a push: a sha that was never pushed as the tip has no run to wait for. Pushing HEAD
+instead would ship the unfinished work; never reset HEAD to get there.
+
+The push targets the branch being delivered (`main` here). Two cases where it does not apply:
+
+- The sha is already on a remote branch: skip the push, it is useless. A sha that was pushed earlier has a CI run
+  only if it was the tip of a push; if it never was, no run exists to wait for.
+- The push is refused as non-fast-forward (the sha is not a descendant of `origin/main`, or `origin/main`
+  has moved past it): **never force it**, `--force` would rewind the remote branch. The sha cannot be delivered
+  that way: stop and ask the human.
+
 ## Where to run
 
 Every `cadence` / `raf` command works on the git repository of the current directory. When the

package/skills/lead/SKILL.md

@@ -96,7 +96,7 @@ tail -n +1 -F .cadence/runs/<id>/journal.log     # from the folder the wave was
 ```
 
 Each line it prints reaches this conversation as it happens: relay it to the human in one short sentence, and
-bring a question back at once (`--resume --answer`). That follow-up replaces any waiting loop: still no polling,
+bring a question back at once (`--resume --wave <wave> --answer`, the command printed under the question). That follow-up replaces any waiting loop: still no polling,
 no `sleep`. The human can also watch from a terminal with `cadence orchestrate --status --watch` (table refreshed
 every 10 s, `--interval <s>` to change it; it stops by itself when no wave is running).
 
@@ -104,10 +104,10 @@ every 10 s, `--interval <s>` to change it; it stops by itself when no wave is ru
 another command: `cadence orchestrate --drop <project>:<lot>` takes a lot out of the wave — a lot not started never starts, a lot
 with a session running lets that session finish, then it is handed back to the lead (its commits stay); a lot that depended on it is
 handed back too. `cadence orchestrate --stop-after-current` lets the sessions running finish and starts nothing else: the wave
-ends `interrupted`, and `--resume` takes it up again. To take a lot out of a wave that is already stopped, use
-`--resume --drop <project>:<lot>` (the lot is handed back instead of being replayed). Neither kills a session.
+ends `interrupted`, and `--resume --wave <wave>` takes it up again (the command printed names the wave). To take a lot out of a wave that is already stopped, use
+`--resume --wave <wave> --drop <project>:<lot>` (the lot is handed back instead of being replayed). Neither kills a session.
 
-**One worktree per lot is experimental and not enabled** (`orchestrate.worktrees: true`, L279): `cadence orchestrate` refuses it (exit 2, `--dry-run` too) while lots L299, L300 and L301 are not done, unless `CADENCE_EXPERIMENTAL_WORKTREES=1` is set (the mode's tests only) — never set it for a real wave. Its options exist but belong to that mode: `--resume <wave> --integrate <project:lot>` replays a lot handed back at the integration step (the wave's output names that exact command), `--replay <project:lot>` also after a refused plan write, `--remove-worktree <project:lot> [--abandon-commits]` removes a kept worktree and branch, and `cadence orchestrate --status` and `cadence lead tour` list the worktrees kept by waves (nothing to list in the default mode).
+**One worktree per lot** (`orchestrate.worktrees`, L279) is on by default in cadence's own `cadence.yaml` since 2026-10-25 (L320) and off in a project that does not set the key (the key is the whole switch: no environment variable). Two independent lots of one repository then play at once, each in its own worktree, and the program integrates them. Its options belong to that mode: `--resume --wave <wave> --integrate <project:lot>` replays a lot handed back at the integration step (the wave's output names that exact command), `--replay <project:lot>` also after a refused plan write, `--remove-worktree <project:lot> [--abandon-commits]` removes a kept worktree and branch, and `cadence orchestrate --status` and `cadence lead tour` list the worktrees kept by waves (nothing to list in the default mode).
 
 **Delivering while the wave runs.** A lot that turns **ready** in the journal is not left waiting: once the lead has re-verified it (section 3, point 2) and recorded its verdict (`raf done`), it delivers that lot at once, without waiting for the end of the wave. The re-check runs at that sha in a throwaway `git worktree add --detach <tmp> <sha>` (removed afterwards), never in the shared tree, which holds the lots still running. Take the sha to deliver from `git log`: the last commit of the ready lot such that no commit of a lot that is not ready (running, queued, in question, handed back) sits beneath it — the same « livrable jusqu'à » the final table prints. Push that sha alone (`git push origin <sha>:main`, never HEAD, which holds the code of lots still running), then `cadence deliver --dry-run --sha <sha>` and `cadence deliver --sha <sha>`: `deliver` accepts a `--sha` during a wave of the same repository when none of its commits belongs to a lot that is not ready, and refuses otherwise, naming the lots. Without `--sha` it stays refused until every lot of the repository is ready or handed back. The wave's sessions keep committing in the working tree: `--sha` never reads it. What the log keeps is `<sha>`, unless the delivery script declares another deployed commit in `CADENCE_DEPLOYED_FILE`; if HEAD moved during the delivery without that declaration, `deliver` warns (« la tête a avancé pendant la livraison ») and the log keeps `<sha>`: it is not a failure. This is the measured gain: a ready lot used to wait for the slowest lot of its wave (1,554 lot-minutes between « ready » and the end of the wave over 28 waves).
 
@@ -124,9 +124,9 @@ mechanical lot. Exit code: 0 all ready · 1 some lots handed back · 2 refused b
 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
+questions back (`--resume --wave <wave> --answer <project>:<lot> "…"`, naming the wave: a bare `--resume` is refused when several waves are unfinished), look at the UX reviewer's captures and record
 `raf ux` (the orchestrator reports its verdict, it never records it; who decides it is the `lead.ux` setting, section 2c), re-verify (section 3, point 2),
-`raf done`, push and deliver. **A locked acceptance test that contradicts the sheet** (the lot is handed back with `verrou des tests d'acceptation`, or the session's question says its own test is wrong, e.g. a regex that rejects a sentence the sheet allows) has a path, and it is the lead's, never a session's: correct the test in the working tree (the sheet is left as it is; if it was amended, **commit it first, citing the lot**: an amended sheet whose every commit cites the lot is accepted, L217, never put it back to the red state), then `cadence spec reseal <lot> <test> --reason "why it contradicts the sheet"` (outside any wave): the program redoes the fingerprint of that one test, writes the reason in `acceptation.json` (`resceaux`) and as a note of the lot, commits both, and the lock keeps everything else. For a **delivered** lot (`vert: true`) whose contract does not change but whose test is unstable, add `--porteur <the lot in progress that carries the fix>`: the commit and the note cite that lot, `vert` stays true (L212). It refuses a lot that is neither in progress nor delivered, a sheet with uncommitted changes or touched by a commit that does not cite the lot, and any other listed test touched, and during a wave of that repository. It is atomic (a refused commit restores `acceptation.json` and the test), with a plan kept read-only by another tool it leaves the plan untouched and says a note is to be added by hand, with an untracked plan or one outside the repository it writes the note but does not commit it (`plan à commiter`: do not add it again), and if the commit of the note is refused the reseal stays done and the error says to commit the plan by hand. It is also refused while a wave that is not `done` (stopped on a question or the quota, or still alive) keeps open any lot of that repository still `doing` in its plan, **the resealed lot, the porteur or any other lot of the repository** (the lock hands back all of them, L238; a lot `done` or absent in the plan, an old abandoned wave, a lot of another repository with the same id never block): the error is a single message, also when a live wave holds the repository lock: it lists every wave (the live ones and the stopped ones) with its launch folder and its lots and gives, for each stopped wave, ONE command to run as it stands, `cd <launch folder> && cadence orchestrate --resume <wave> --drop <project>:<lot> --drop <project>:<lot>` (a `--drop` per open lot of the repository, queued ones not yet `doing` in the plan included, since `--resume` replays the whole wave; or `--resume <wave> --answer …` to let it go on); a wave still alive is waited for. Close them **first**, reseal afterwards. Do it **between two sessions**, never inside one: a resealed commit that belongs to a session of the wave is not adopted (still a lock violation), and sessions are forbidden the command. Then continue the lot: a new wave `cadence orchestrate <project>:<lot>` when it was handed back (`--resume` skips finished lots). Minor findings and proposed sub-tasks come back in the table: adding them to
+`raf done`, push and deliver. **A locked acceptance test that contradicts the sheet** (the lot is handed back with `verrou des tests d'acceptation`, or the session's question says its own test is wrong, e.g. a regex that rejects a sentence the sheet allows) has a path, and it is the lead's, never a session's: correct the test in the working tree (the sheet is left as it is; if it was amended, **commit it first, citing the lot**: an amended sheet whose every commit cites the lot is accepted, L217, never put it back to the red state), then `cadence spec reseal <lot> <test> --reason "why it contradicts the sheet"` (outside any wave): the program redoes the fingerprint of that one test, writes the reason in `acceptation.json` (`resceaux`) and as a note of the lot, commits both, and the lock keeps everything else. For a **delivered** lot (`vert: true`) whose contract does not change but whose test is unstable, add `--porteur <the lot in progress that carries the fix>`: the commit and the note cite that lot, `vert` stays true (L212). It refuses a lot that is neither in progress nor delivered, a sheet with uncommitted changes or touched by a commit that does not cite the lot, and any other listed test touched, and during a wave of that repository. It is atomic (a refused commit restores `acceptation.json` and the test), with a plan kept read-only by another tool it leaves the plan untouched and says a note is to be added by hand, with an untracked plan or one outside the repository it writes the note but does not commit it (`plan à commiter`: do not add it again), and if the commit of the note is refused the reseal stays done and the error says to commit the plan by hand. It is also refused while a wave that is not `done` (stopped on a question or the quota, or still alive) keeps open any lot of that repository still `doing` in its plan, **the resealed lot, the porteur or any other lot of the repository** (the lock hands back all of them, L238; a lot `done` or absent in the plan, an old abandoned wave, a lot of another repository with the same id never block): the error is a single message, also when a live wave holds the repository lock: it lists every wave (the live ones and the stopped ones) with its launch folder and its lots and gives, for each stopped wave, ONE command to run as it stands, `cd <launch folder> && cadence orchestrate --resume --wave <wave> --drop <project>:<lot> --drop <project>:<lot>` (a `--drop` per open lot of the repository, queued ones not yet `doing` in the plan included, since `--resume` replays the whole wave; or `--resume --wave <wave> --answer …` to let it go on); a wave still alive is waited for. Close them **first**, reseal afterwards. Do it **between two sessions**, never inside one: a resealed commit that belongs to a session of the wave is not adopted (still a lock violation), and sessions are forbidden the command. Then continue the lot: a new wave `cadence orchestrate <project>:<lot>` when it was handed back (`--resume` skips finished lots). Minor findings and proposed sub-tasks come back in the table: adding them to
 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).
 

package/skills/orchestrate/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: orchestrate
+description: The exact command line of `cadence orchestrate` — launch a wave ("lancer une vague orchestrate", "start an orchestrate wave", run lot X with model Haiku) and resume it with `--resume [--wave <wave>]`. Use it before writing any `cadence orchestrate` command, without going through /lead. Syntax `<project>:<lot>[@<model>]`, a lot id with « / » kept as is.
+---
+
+# orchestrate — the command line of a wave
+
+`cadence orchestrate` runs one fresh short session per step of each lot (write, review, correction, delivery of
+the sheet). This page is only the syntax; the lead's workflow is the `cadence:lead` skill and every option is in
+`docs/orchestrate.md` of the cadence package.
+
+## Launch
+
+```sh
+cadence orchestrate <project>:<lot>[@<model>] [<project>:<lot>[@<model>] …] [--wave <id>] [--budget 2M]
+cadence orchestrate maritime-atlas:Q4/accueil-4-ux12@haiku
+cadence orchestrate finance-tracker:L41 cadence:L18@haiku --budget 1.5M
+```
+
+- One positional argument per lot: `<project>:<lot>`, then `@<model>` to give that lot a model (`@haiku`, `@sonnet`,
+  `@opus`). The project is what comes before the **first `:`**, the model what comes after the **last `@`**.
+- **A lot id may contain « / »** (sub-tasks of a plan kept read-only by another tool, `Q4/accueil-4-ux12`): write it as is, never escape
+  it, never replace it, never split it. Quote the whole argument only if the shell needs it.
+- There is no `--lot` and no `--model`: the lot and its model are always in the same argument, `<project>:<lot>@<model>`.
+  From inside a project, `cadence orchestrate L18` is enough.
+- `--dry-run` first when a precondition is in doubt (nothing is started); `--budget` takes `1.5M`, `800k` or `1500000`;
+  `--goal "<what done looks like>"` for a single lot whose title is stale.
+
+## Resume
+
+A wave that stopped (a question, the quota, an interruption) is resumed with the same program, never with a new wave:
+
+```sh
+cadence orchestrate --resume                     # the only unfinished wave of the folder
+cadence orchestrate --resume --wave <wave>       # a named wave (required when several are unfinished)
+cadence orchestrate --resume --wave <wave> --answer <project>:<lot> "reply"
+```
+
+`--resume` takes no lot: it replays the lots of the wave. `cadence orchestrate --status` shows the live waves of the machine and the table of the folder's latest wave; `--resume` with no wave lists the unfinished ones when there are several.

package/templates/orchestrate/fix-docs.md

@@ -7,11 +7,11 @@ Commits of the lot so far:
 Documentation behind the lot:
 {{constats}}
 
-Read the diff of each commit above (`git show <sha>`), the project's CLAUDE.md, the README, the pages of `docs/`, the CHANGELOG and the news entries; update each document the change makes false or leaves out. A document that the change really leaves true is left alone: say why under "choix".
+Read the diff of each commit above (`git show <sha>`), the project's CLAUDE.md, the README, the pages of `docs/`, the CHANGELOG and the news entries; update each document the change makes false or leaves out; where the README is a short home page, the detail goes in the pages of `docs/` and the README receives only a link. A document that the change really leaves true is left alone, but the gap stays open for the program until it is acknowledged: {{ack}} A session that neither writes the documentation nor acknowledges the gap hands the lot back to the lead: it never goes to review. Say why under "choix" as well.
 Rules: commit each document as soon as it is right, with explicit paths (never `git add -A` or `commit -a`), and a message that cites the lot (`docs({{lot}}): …`); run the project's documentation checks if it has any, and its full test suite and build if a test reads the documents, before reporting; do not push, deliver, run `raf done`, `raf ux` or `raf review`.
 Never run `git checkout` or `git switch` to another commit or branch in this repository: the orchestrator watches it and a moved HEAD breaks the other sessions of the wave. To look at another sha, use a throwaway `git worktree add --detach <tmp> <sha>`, removed afterwards.
 {{elsewhere}}
-Do not stop to ask: an interpretation you settle yourself goes under "choix" with the alternative you did not take; "questions" stays empty. Making no commit is a valid outcome when every document is already true.
+Do not stop to ask: an interpretation you settle yourself goes under "choix" with the alternative you did not take; "questions" stays empty. Making no documentation commit is a valid outcome only with the acknowledgement above.
 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/implement.md

@@ -9,7 +9,7 @@ full test suite and build before reporting; do not push, deliver, run `raf done`
 `raf review`.
 Sealed test of ANOTHER lot: if what your own sealed tests require contradicts a sealed acceptance test of another lot (an `acceptation-<lot>.json` that is not yours), it is a question to the lead naming both tests (file and `Rn — …` name of each): never modify, rewrite or reseal it and never pick a side. Stop there and put the question in your report. The program compares the fingerprints of the sealed tests of every other lot at the end of each session and hands your lot back, naming the first offending commit, before any review.
 Never run `git checkout` or `git switch` to another commit or branch in this repository: the orchestrator watches it and a moved HEAD breaks the other sessions of the wave. To look at another sha, use a throwaway `git worktree add --detach <tmp> <sha>`, removed afterwards.
-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.
+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. Where the project's README is a short home page, the detail of a change goes in the pages of `docs/` and the README receives only a link to that page.
 Self-check before handing back (the recurring findings of the reviews). Go through this list point by point on your own commits before you report, and fix what is missing:
 - documentation: the README and the architecture documentation describe the behaviour, updated in the same commits as the behaviour (and the CHANGELOG);
 - tests: one test per rule of the fiche, named « Rn — … »; with no fiche, one test per business rule of the lot, named after it;

package/templates/orchestrate/precheck.md

@@ -2,7 +2,7 @@ Pre-check for lot `{{lot}}` — "{{titre}}" — of the repository `{{chemin}}`,
 Question: is the deliverable of this lot ALREADY in the repository (done by another lot, or by a correction)?
 Goal of the lot: {{objectif}}
 {{repos}}
-Read the lot, its notes and sub-tasks in the plan (`.cadence/raf.yaml`, the legacy `docs/plan/raf.yaml`, or the file named by `plan:` in `cadence.yaml`),
+{{lecture}}
 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