@sylad/cadence 1.8.0 → 1.10.0

package/.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
     {
       "name": "cadence",
       "description": "Session start and close rituals driven by a versioned plan (raf), and deliveries proven by their effect. Needs the cadence CLI (npm i -g @sylad/cadence).",
-      "version": "1.8.0",
+      "version": "1.10.0",
       "source": "./",
       "author": {
         "name": "Sylvain Ladoire"
@@ -17,7 +17,7 @@
     {
       "name": "cadence-hud",
       "description": "A status band above the Claude Code prompt: context, 5 h / 7 d quota windows, cost per model, agents of the session and the running cadence orchestrate waves. Works without the cadence CLI, except the per-project plan progress, which needs `cadence` on the PATH.",
-      "version": "0.4.3",
+      "version": "0.5.0",
       "source": "./plugins/cadence-hud",
       "author": {
         "name": "Sylvain Ladoire"

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "cadence",
   "description": "A repo-native working method: session start and close rituals driven by a versioned plan (raf), deliveries proven by their effect, and three reviewer agents (UX, code, QA).",
-  "version": "1.8.0",
+  "version": "1.10.0",
   "author": { "name": "Sylvain Ladoire" },
   "homepage": "https://github.com/Sylad/cadence",
   "repository": "https://github.com/Sylad/cadence",

package/README.md

@@ -1,73 +1,46 @@
 # cadence
 
-A small working method that lives in your repository: a versioned plan linked to your commits, waves of fresh AI sessions driven by a program, and deliveries proved by their effect.
-Solo developers and AI-assisted sessions lose track of *what is left to do* and *what each commit was for*; cadence keeps both in plain files next to the code.
-**raf** is the plan, **news** the changelog with screenshots, **session** the facts to open and close a day, **deliver** waits for the CI, deploys, then checks the effect.
-**orchestrate** runs a lot through spec, review, code and UX passes, each in its own session; the **lead** decides, re-verifies and delivers.
-Four [Claude Code](https://claude.com/claude-code) skills, three reviewer agents and a status-band plugin (`cadence-hud`) turn it into rituals.
-
-<picture>
-  <source media="(prefers-color-scheme: dark)" srcset="docs/cycle-vague-dark.svg">
-  <img alt="A lot goes through spec, mockup, accept, implement, review, ux and deliver; the lead picks the lots, answers the questions, re-verifies and delivers" src="docs/cycle-vague-light.svg">
-</picture>
+A small working method that lives in your repository: a versioned plan linked to your commits,
+waves of fresh AI sessions driven by a program, and deliveries proved by their effect.
+It is for solo developers and AI-assisted sessions who lose track of *what is left to do* and *what each commit was for*:
+cadence keeps both in plain files next to the code, and [Claude Code](https://claude.com/claude-code) skills turn it into rituals.
 
 ## Start
 
 ```sh
-npm install -g @sylad/cadence    # or: npx -p @sylad/cadence raf …
-raf init                         # docs/plan/raf.yaml + a post-commit hook
+npm install -g @sylad/cadence
+raf init
 raf add "My first lot" --estimate 1
 ```
 
 Then `raf start L1`, commit with `feat(L1): …`, `raf now` to see where you are, `raf done L1` when it is finished.
 
-## Where to read more
-
-| Page | What it covers |
-|---|---|
-| [docs/raf.md](docs/raf.md) | the plan: commands, plan file, foreign plan formats, Gantt |
-| [docs/orchestrate.md](docs/orchestrate.md) | waves of sessions: budgets, spec, accept and review steps, neighbouring repositories |
-| [docs/deliver.md](docs/deliver.md) | delivery: wait for CI, deploy, verify the effect |
-| [docs/spec.md](docs/spec.md) | the screen and back-end sheets, `cadence spec check\|qa\|reseal` |
-| [docs/lead.md](docs/lead.md) | the lead workflow and `cadence lead tour` |
-| [docs/stabilite.md](docs/stabilite.md) | what is guaranteed from 1.0.0 and what is not |
-
-Also: [news](docs/news.md) (changelog, UX, code and QA reviews, documentation that follows the code), [session](docs/session.md), [corrections](docs/corrections.md), [perf](docs/perf.md), [skills and agents](docs/skills.md), [cadence-hud](docs/cadence-hud.md), [releasing](docs/releasing.md), [overview](docs/overview.md), [how it all works](docs/fonctionnement.md) (four figures).
-
-<details>
-<summary>The four tools in short</summary>
-
-- **raf** (French *reste à faire*, "what is left to do"): the plan, linked to your commits by the lot id in the message, computed from `git log` and never stored.
-- **news**: a user-facing changelog with screenshots, tied to the plan; a lot is not done until its entry is written.
-- **session**: `session start` and `session close` gather the facts of a work session.
-- **deliver**: wait for the CI of the pushed commit, run the deploy commands, then **verify the effect**; a delivery is done only when its checks pass. A failed delivery is logged as a *red delivery*.
-- **perf**: `cadence perf` is the dashboard of the workflow (speed next to quality, `⚠` on a trend), including the red deliveries and the blocking QA findings; `cadence lead tour` opens with its *perf header*, one line per `⚠`, nothing when stable ([docs/perf.md](docs/perf.md)).
-
-Reviews are opt-in gates: `ux-reviewer` (no user-facing change is done before its usability review), `code-reviewer` (no lot with commits is done before its code review) and `qa-reviewer`, which walks the delivered app in a real browser.
-
-</details>
-
-## What's new
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/cycle-vague-dark.svg">
+  <img alt="A lot goes through spec, mockup, accept, implement, review, ux and deliver; the lead picks the lots, answers the questions, re-verifies and delivers" src="docs/cycle-vague-light.svg">
+</picture>
 
-Two lines per version; the long form is in [docs/whats-new.md](docs/whats-new.md) and the full history, with dates, in [CHANGELOG.md](CHANGELOG.md).
+## Install as a Claude Code plugin
 
-- **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](docs/stabilite.md) lists what is guaranteed.
+```
+/plugin marketplace add Sylad/cadence
+/plugin install cadence@cadence        # skills and reviewer agents; needs @sylad/cadence above
+/plugin install cadence-hud@cadence    # the status band, works without the CLI
+```
 
-<details>
-<summary>Older versions (0.10.0 to 0.28.0)</summary>
+Details: [docs/skills.md](docs/skills.md) and [docs/cadence-hud.md](docs/cadence-hud.md).
 
-Each is a paragraph in [docs/whats-new.md](docs/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`.
+## Where to read more
 
-</details>
+- [docs/raf.md](docs/raf.md): the plan, its commands and its file.
+- [docs/orchestrate.md](docs/orchestrate.md): waves of sessions and their budgets.
+- [docs/deliver.md](docs/deliver.md): wait for the CI, deploy, verify the effect.
+- [docs/spec.md](docs/spec.md): screen and back-end sheets.
+- [docs/lead.md](docs/lead.md): the lead workflow.
+- [docs/overview.md](docs/overview.md): the longer introduction and the map of every page.
+- [docs/fonctionnement.md](docs/fonctionnement.md): how it all works, in four figures.
+- [docs/stabilite.md](docs/stabilite.md): what is guaranteed from 1.0.0.
+- [docs/whats-new.md](docs/whats-new.md) and [CHANGELOG.md](CHANGELOG.md): what changed.
 
 ## License
 

package/agents/code-reviewer.md

@@ -21,8 +21,8 @@ fact. If the path or the id is missing, or the lot has no commit to review, say
    folder's CLAUDE.md does not count unless it names this project. Then find the commands that
    test, type-check, lint and build: in the README, then in the manifest (`package.json` scripts,
    Makefile, `pyproject.toml`…).
-2. **Read the lot**: its title, notes and sub-tasks in the plan (`docs/plan/raf.yaml`, or the file
-   named by `plan:` in `cadence.yaml`). That is the goal the commits are measured against. When the
+2. **Read the lot**: its title, 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`). That is the goal the commits are measured against. When the brief gives a "Goal of the lot", that goal of the lot given in the brief takes precedence over the title in the plan (a title can be stale; the goal was given on purpose): measure the commits against it, not against the title. When the
    lot has only a title, also read the bodies of its commits and any spec the lot cites.
 3. **Get the commits from the tool**: `raf commits <id>` prints exactly the set the gate counts —
    `<sha> <subject>` per line, oldest first, the commits that only touch the plan left out. Only

package/agents/doc-keeper.md

@@ -0,0 +1,19 @@
+---
+name: doc-keeper
+description: Generic librarian. For one repository and one lot, reads the diff of the lot and the project's map of documents (docs.sync of cadence.yaml, README, docs/, CHANGELOG, Nouveautés), says which documents must change, then updates them (writing session) or only lists them (read-only session). A document outside the repository only when the configuration names it (docs.articles), and then it proposes a lot for that repository's plan and never writes it. Called by orchestrate when docs.sync reports a document behind the lot, or by the lead by hand.
+tools: Read, Write, Edit, Grep, Glob, Bash
+---
+
+You keep the documentation of one repository true to the work of one lot. You write documents; you never write the code of the lot.
+
+Follow the brief you are given. The method:
+
+1. **Read the diff of the lot.** The commits that cite the lot (`git log`, then `git show <sha>` for each; never a `git diff` range, which would take in the commits of other lots). Note what the change makes true or false for a reader: a behaviour, a command, a key, a default, a name, a file.
+2. **Draw the map of the documents.** The `docs.sync` rules of the project's `cadence.yaml` (the code paths and the documents they call for), then what the project keeps besides: the README, the pages of `docs/`, the CHANGELOG, the Nouveautés / What's new entries, the architecture document. Read the project's CLAUDE.md first for its own rules on documentation. Nothing about a folder or a machine comes from you: only this project's files.
+3. **Say which documents must change, and why.** A lot that changes how the tool works (a behaviour, a command, a key, a default) is written in the pages of `docs/`, in full; the README is a short home page and receives only a link to that page, never the detail (an option, a key, a path, a flag). A README that grows by a paragraph is a finding, not a document brought up to date. For each: the file, the passage, the sentence that the diff makes false or leaves out. A document the diff does not touch the truth of is not listed.
+4. **Act according to the session.**
+   - Writing session: update each document (the detail in `docs/`, a link in the README), in the language and the style it already has. Test the project's documentation checks if it has any (links, doc tests). Commit as soon as a document is right, with explicit paths (never `git add -A` or `commit -a`) and a message that cites the lot (`docs(<lot>): …`). A CHANGELOG or Nouveautés entry only if the project keeps one for this kind of change.
+   - Read-only session (no write tool, or a brief that says read-only): change nothing; list the documents of step 3 with the passage to write, ready to be applied by someone else.
+5. **A document outside the repository** is yours only when the configuration says so: the brief then lists the entries of `docs.articles` (the cadence.yaml of the project: « this project is also described by this file of that repository », with the absolute path of the repository, open to you for reading). Never guess such a file, never go looking for one. Do not edit it, and never write to the plan of that repository (no `raf add`, no edit of its plan file): write a proposed lot instead — a title and a body that name the repository, the file, the passage and the sentence to change — and put it in the `resume` of your report, starting with « lot proposé ». The lead decides whether it enters that repository's plan.
+
+Never push, deliver, or run `raf done|start|note|review|ux`. Never run `git checkout` or `git switch` to another commit or branch in this repository. Do not launch subagents. Do not stop to ask: an interpretation you settle yourself goes under "choix" with the alternative you did not take. A document you could not check against the code goes under "nonVerifie". Give the report in the structured output the brief asks for.

package/agents/precheck-reader.md

@@ -6,7 +6,7 @@ tools: Read, Grep, Glob, Bash
 
 You check, quickly, whether the deliverable of one lot of a plan is already in the repository. You report; you never edit code.
 
-Follow the brief you are given: read the lot in the plan, then look for each part of its deliverable in the code, the tests and `git log`. A lot with no commit of its own is the normal case here — do not stop for that, it is the reason for the check.
+Follow the brief you are given: the brief tells you how to get the lot (it carries it, or tells you where to read it in the plan), then look for each part of its deliverable in the code, the tests and `git log`. A lot with no commit of its own is the normal case here — do not stop for that, it is the reason for the check.
 
 - Do not run the test suite, the type-check, the linter or the build: this is a quick look.
 - Do not modify, commit, push, or run `raf start|done|note|review|ux`. Do not launch subagents.

package/agents/qa-reviewer.md

@@ -107,7 +107,7 @@ a delivery rarely changes them all:
 - the pages that call the changed endpoints (`raf commits <id>` and the diff tell which routes
   changed; the `api:` lines of the expectations, and the calls you see a page make, tell which
   pages use them);
-- the pages of the screens the lot changed (its title and notes in the plan, and
+- the pages of the screens the lot changed (the goal of the lot given in the brief takes precedence over the title in the plan; then its notes in the plan, and
   the components in its commits, name them);
 - the home page.
 
@@ -165,7 +165,7 @@ A short report:
   (/players shows no player)", "no expectations file: 13 pages walked, 1 defect, 8 suspects, draft
   returned". It is the last line of the report.
 
-Give screenshots and snapshots a relative file name only (e.g. `page-home.png`), never an absolute path: the Playwright MCP writes them under `.playwright-mcp/` (list them in the report if git does not ignore that folder), or in the wave's output directory outside the repository when a wave launched it. Other temporary files go in a temporary directory outside the repository, or in the one
+Give screenshots and snapshots the absolute path of the capture directory your brief names when it names one (a wave's Playwright server resolves a bare name against the repository, not its output directory); with no such directory in the brief, a path under `.playwright-mcp/` (e.g. `.playwright-mcp/page-home.png`: the Playwright MCP resolves a bare file name against the repository, where it would land at the root and dirty the working tree) and no other path inside the repository (list them in the report if git does not ignore that folder). Other temporary files go in a temporary directory outside the repository, or in the one
 the caller names; remove them, or list their paths in the report — except the QA browser profile, which is kept for the next pass. The working tree is left as you
 found it.
 

package/agents/reference-analyst.md

@@ -0,0 +1,25 @@
+---
+name: reference-analyst
+description: Reference document analyst. Reads the pages that `cadence ref add` rendered for one document (a screen mock-up PDF, a spec with figures, a norm), page by page and then zone by zone at full resolution, and writes one reading — an inventory of what the document shows (screens, components, states, verbatim texts, design tokens, tables, message templates, schemas, text-figure links, status badges, silences) — in the JSON format of `templates/inventaire.json`. Everything measurable goes through `cadence ref measure`; what cannot be read for sure is marked incertain with its cause. Writes only its reading, validates it with `cadence ref check`. Used by `cadence ref analyse` and by the orchestrator, not by hand.
+tools: Read, Write, Bash, Grep, Glob
+---
+
+You read one reference document and write down what it shows. You write one file, your reading; you never write code, specs or the plan, and you never decide what the project should do with what you read.
+
+Follow the brief you are given. It names the document folder, the pages that were rendered (`pages/page-<n>.png`, 200 dpi), the file to write, the model to copy and the exact commands to measure and to validate. The folder also holds `document.json`: the positioned text of every page (each line with its box `x, y, l, h` in pixels of the rendered page), the images, the figure index with the passages that cite each figure, and the unresolved links. The method:
+
+1. **Look at every page whole first.** Open each rendered page with the Read tool and say to yourself what it is: a mock-up, a requirements page, a figure, a table, a scan. A page you did not open is a page you did not read.
+2. **Then every zone at full resolution.** A whole page is too small to read a label, a threshold or a table cell. Crop the zone (`cadence ref measure` gives the boxes of the shapes of a zone: `--quoi boites`) and look at the crop, or at the embedded image under `images/`, before writing anything about it.
+3. **Measure whatever is measurable, never estimate it by eye.** A colour, a contrast, a size, a box, a font size: `cadence ref measure <slug> <page> <zone> --quoi couleurs|contraste|boites|texte`, with the commands of the brief. An element whose numbers come from that command is `confiance: mesure` and its `point` or zone says where it was sampled. Text read by tesseract on a whole page is `ocr: true` and never `lu`.
+4. **Copy every visible text verbatim**: same characters, same case, same units (`120 KT` is not `120 kt`). One convention for labels: every visible text outside a table or a message template is a `texte` with its role from the closed list of `templates/inventaire.json`, including the label of a component (the button `Layers` is a `composant` and a `texte`). The text of a table or a template belongs to it, not to a `texte`.
+5. **Link every figure to the passages that cite it.** For each figure of `document.json`, read the passages that cite it, then the figure, and write a `lien`: `confirme` when the figure says what the text says, `precise` when the figure settles an ambiguity of the text (say the ambiguous reading, the one you keep and why, from what the figure draws), `contredit` when the two disagree (give the two statements, never pick one). A figure with no caption, or a citation with no figure: say so, or declare it not found.
+6. **What the document does not show is a `silence`**, written as a question that ends with `?`: a state, a message, a rule a developer will have to decide. Do not answer it.
+7. **Never guess.** An element you cannot read for sure (blurred, cut, too small, two readings possible) is `confiance: incertain` with its `cause`, never `lu`. Never invent an element to complete a list, never leave one out because it looks like another. A text that is too small to measure (under about 8 px at the render) is `incertain` with that cause.
+8. **Write the reading** to the file of the brief, in the format of `templates/inventaire.json` but with `genre: "lecture"`, the `document` `slug` and `sha256` of `document.json` (copy them, never retype them), and no `pages` key. Every id is `<slug>#<type>-<n>`. Then run `cadence ref check` on it, with the command of the brief, until it passes: a reading that does not pass is not a result.
+
+- Never write `usage`, tokens or costs in the reading: the program that launched you counts them. Never write the `sha256` of another file than `document.json`.
+- Never open another file of `lectures/` than the one you write: another reader may have written its own reading of the same document, and a reading made with the other in hand is not independent, so it measures nothing.
+- Read only the document folder named in the brief and the model. Never look for, open or use an expected inventory, an answer key or a test corpus: the reading is yours alone, and a reading made with the answer in hand measures nothing.
+- You write only the reading file: no other file, no commit, no change in the repository. Do not push, deliver, run `raf start|done|note|review|ux`, or launch subagents.
+- A question a human must settle (a figure that contradicts its text, an element you cannot read) goes in `questions` of your report, as well as in the reading (`contredit`, `incertain`, `silence`).
+- Give the report in the structured output the brief asks for.

package/agents/reference-verifier.md

@@ -0,0 +1,19 @@
+---
+name: reference-verifier
+description: Third look at a reference document. Receives only the elements that ONE of two independent readings carried and the other did not (each with the rendered page and a crop of its zone), looks at the crop and says for each one whether the document really shows it (confirme) or not (ecarte), with the reason. Writes nothing. Used by `cadence ref analyse` after `cadence ref diff`, not by hand.
+tools: Read, Bash
+---
+
+You are the third look on a reference document. Two readers read the same pages separately; they agree on most elements, and disagree on a few. The brief lists only the elements that **one** reader wrote and the other did not, each with a number, what was written, the rendered page and a **crop** of the zone it names. You never see the readings themselves, nor which reader wrote what, and you do not read the rest of the document: only the elements of the brief and their crops.
+
+For each numbered element:
+
+1. **Open the crop** with the Read tool, and say to yourself what is drawn there. If the brief says there is no crop (the page was not rendered, or the zone is outside it), open the whole page, and say so in the reason.
+2. **Compare what was written with what is drawn**, character by character for a text (same characters, same case, same units: `120 KT` is not `120 kt`), value by value for a colour, a size or a cell. A number or a colour that can be measured is measured, never estimated by eye: `cadence ref measure` with the command of the brief.
+3. **Rule**: `confirme` when the crop shows exactly what was written, `ecarte` when it does not show it, or shows something else, or the element is a duplicate of another written differently. Never guess: if you cannot tell (blurred, cut, too small), the answer is `ecarte` with that reason, never `confirme`. Never rewrite an element, never correct it, never add one.
+
+Every verdict carries a `raison`: one sentence that says what the crop shows. A verdict without a reason, or with a verdict other than `confirme` or `ecarte`, is counted as no answer.
+
+- You write no file, you make no commit, you change nothing in the repository. Do not push, deliver, run `raf start|done|note|review|ux`, or launch subagents.
+- Never look for, open or use an expected inventory, an answer key or a test corpus, nor any file of `lectures/`.
+- Give the report in the structured output the brief asks for: `decisions` (one object per numbered element: `numero`, `verdict`, `raison`) and `questions` (what a human must settle).

package/agents/spec-writer.md

@@ -10,7 +10,7 @@ Follow the brief you are given. The method:
 
 1. **Read the charter first.** The project's CLAUDE.md, its CSS and variables, the neighbouring components and pages, `docs/qa/expectations.md`, the routes and API contracts already present. The mockup must look like the product: reuse what exists, invent nothing when an equivalent exists.
 2. **List the states before drawing**: empty, loading, error, and loaded when there is data. Each is an addressable section `#etat-<état>` of one static `maquette.html` (HTML + CSS, no business JavaScript). Each field of the sheet carries `data-testid="<field id>"`.
-3. **Render and look.** Capture each state at **1440 px** and **390 px** wide with the browser tool (Playwright), a relative file name only (`maquette-<état>-<largeur>.png`), and look at every capture before keeping it: a mockup you did not look at is not checked. Copy the kept captures into the spec folder.
+3. **Render and look.** Capture each state at **1440 px** and **390 px** wide with the browser tool (Playwright), named `maquette-<état>-<largeur>.png`, with the absolute capture-directory path your brief gives in front of the name (a bare name lands in the repository), and look at every capture before keeping it: a mockup you did not look at is not checked. Copy the kept captures into the spec folder.
    Before keeping a state, check its sample data: compute the weekday of every date shown (`date -d`), never write it from memory.
 4. **Write the sheet** in the format of the template of the brief, and run `cadence spec check` on it until it passes. Every rule is `sourcee` (say where it comes from) or `hypothese` (say what would change if it were wrong, in `si_faux`). Never dress a guess as a source.
 5. **Costly choices are questions.** If a rule would fix a data model or storage, a public or shared API contract or an already published route, a destructive or irreversible action, or contradict an existing sourced rule, do not write it as a hypothesis: stop and ask, in the `questions` of the report. Wording, field order, the error state and spacing are written hypotheses.

package/agents/ux-reviewer.md

@@ -38,7 +38,7 @@ When the brief says "conformity" (the orchestrator, after the code, for a lot th
 
 1. **Look before judging.** Capture the screen with the browser tool available (Playwright or
    equivalent) at **1440 px** and **390 px** wide, in its main states: empty, loaded, error, loading,
-   and the key interaction. Look at every capture. Give screenshots and snapshots a relative file name only (e.g. `page-home.png`), never an absolute path: the Playwright MCP writes them under `.playwright-mcp/` (list them in the report if git does not ignore that folder), or in the wave's output directory outside the repository when a wave launched it. Anything else you create goes in a temporary directory outside the repository, removed afterwards.
+   and the key interaction. Look at every capture. Give screenshots and snapshots the absolute path of the capture directory your brief names when it names one (a wave's Playwright server resolves a bare name against the repository, not its output directory); with no such directory in the brief, a path under `.playwright-mcp/` (e.g. `.playwright-mcp/page-home.png`: the Playwright MCP resolves a bare file name against the repository, where it would land at the root and dirty the working tree) and no other path inside the repository (list them in the report if git does not ignore that folder). Anything else you create goes in a temporary directory outside the repository, removed afterwards.
 2. **Walk the main task** a real user comes for (find, read, compare, act, undo) and count the steps.
 3. **Check, and measure where a number exists:**
    - Nielsen's 10 heuristics — especially visibility of system status, match with the user's words,

package/bin/cadence.js

@@ -13,7 +13,7 @@ const io = {
 
 if (tool === 'raf') {
   process.exitCode = await run(args, io);
-} else if (['news', 'session', 'deliver', 'verify', 'skills', 'orchestrate', 'lead', 'corrections', 'perf', 'spec'].includes(tool)) {
+} else if (['news', 'session', 'deliver', 'verify', 'skills', 'orchestrate', 'lead', 'corrections', 'perf', 'spec', 'ref'].includes(tool)) {
   process.exitCode = await run([tool, ...args], io);
 } else if (tool === '--version' || tool === '-v') {
   const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
@@ -33,6 +33,12 @@ if (tool === 'raf') {
   cadence deliver [--dry-run] [--sha rév] [--config cadence.yaml] [-- arguments du script du projet]
                     CI du sha poussé → déploiement → vérifications de l'effet ;
                     ou le script de livraison du projet (deliver.script), sous verrou et journal
+  cadence ref add <document.pdf> [--sections 3-5,9] [--slug nom]
+                    enregistre un document de référence hors du dépôt : pages rendues, texte positionné, images, index des figures
+                    et des passages qui les citent ; exige poppler, ImageMagick et tesseract (outil absent nommé avec sa commande, code 2)
+  cadence ref measure <slug> <page> <page | x,y | x,y,l,h> [--quoi couleurs|contraste|boites|texte] [--largeur 1440] [--json]
+                    mesure une zone d'une page rendue : couleurs, contraste WCAG 2.2, boîtes, mots OCR et taille de police estimée,
+                    ramenés à 1440 px de large, tolérance déclarée
   cadence verify [--retry secondes] [--sha rév]
                     rejoue les vérifications d'effet (deliver.verify) hors livraison, une passe, en parallèle ;
                     code 0 tout vert, 1 un effet rouge, 2 rien à vérifier ; « session start » la lance aussi
@@ -41,6 +47,8 @@ if (tool === 'raf') {
                     --max-sessions : sessions simultanées, toutes vagues confondues (CADENCE_MAX_SESSIONS)
                     --continue [--until HH:MM] [--priority a,b] : tire seul les lots prêts du plan, jusqu'à une borne
                     --waits [--since AAAA-MM-JJ] : l'attente de créneau de session par jour et par vague, lue dans les journaux
+  cadence lead hold <étiquette> [--ttl minutes] | lead release <étiquette>
+                    déclare, puis rend, une session lancée à la main par le lead : soustraite des créneaux libres
   cadence lead tour [dossier] [--idle 3] [--json]
                     le tableau du lead, sans modèle : une ligne par sous-dossier qui a un plan, ou la ligne du dossier courant
                     s'il est lui-même un projet ; une première ligne « cadence.yaml · ✗ erreur » si priority: est illisible

package/dist/audit.js

@@ -4,19 +4,29 @@ import { check } from './check.js';
 import { parse } from 'yaml';
 import { changedFiles, fileAt, readCommits } from './git.js';
 import { citedRefs, linkCommits, scopeOf } from './link.js';
-import { readDocsConfig, readNewsConfig, readOrchestrateConfig } from './config.js';
+import { PLAN_DEFAULT, PLAN_LEGACY, readDocsConfig, readNewsConfig, readOrchestrateConfig } from './config.js';
 import { ficheHypotheses } from './spec.js';
 import { docSyncGaps, filesOf, gapMessage } from './docsync.js';
 import { loadEntries, newsIssues, PUBLIC_TITLE_DEFAULT, publicTitleTooLong, reusedNewsTitle } from './news.js';
 import { isRecurring } from './recurring.js';
+import { resourceIssues } from './resources.js';
 import { escapeRe, isOpen } from './plan.js';
 /** Chemin de la configuration lue, relatif à la racine : celui de --config, sinon cadence.yaml. */
 function configRel(plan, root) {
     return plan.configFile ? relative(root, plan.configFile) : 'cadence.yaml';
 }
-/** Le plan, sa page Gantt, la configuration lue (cadence.yaml) et les fichiers tenus avec lui (plan.files). */
+/**
+ * Le plan, sa page Gantt, la configuration lue (cadence.yaml) et les fichiers tenus avec lui (plan.files). Le plan par défaut
+ * (.cadence/raf.yaml) compte aussi son emplacement hérité docs/plan/ : après le `git mv` proposé par raf, les anciens commits du
+ * plan et le commit du déplacement (qui liste la suppression et l'ajout) restent des commits de plan seul (L246, fiche plan-dossier-cache R12).
+ */
 export function ownFiles(plan, root) {
-    return new Set([relative(root, plan.path), relative(root, join(dirname(plan.path), 'gantt.html')), configRel(plan, root), ...plan.maintained]);
+    const own = new Set([relative(root, plan.path), relative(root, join(dirname(plan.path), 'gantt.html')), configRel(plan, root), ...plan.maintained]);
+    if (relative(root, plan.path) === PLAN_DEFAULT) {
+        own.add(PLAN_LEGACY);
+        own.add(join(dirname(PLAN_LEGACY), 'gantt.html'));
+    }
+    return own;
 }
 function withoutPlanKey(text) {
     if (text === null)
@@ -160,7 +170,7 @@ export function audit(plan, root, newsDir, today, opts = {}) {
         const m = l.public ? publicTitleTooLong(l.public, max) : reused ? publicTitleTooLong(reused, max) : null;
         return m ? [{ message: `${l.id} : ${reused && !l.public ? m.replace('titre public', 'titre public repris de la Nouveauté') : m}` }] : [];
     });
-    const issues = [...check(lots, { ...linked, byLot: all.byLot }, today, opts.idle ?? 7), ...newsIssues(lots, entries, newsDir, hypothesesOf(root, plan.configFile ?? join(root, 'cadence.yaml'))), ...titles, ...gates, ...docSyncIssues(plan, root, all.byLot), ...(plan.hasPublicField ? missingPublicTitles(lots, entries) : []),
+    const issues = [...check(lots, { ...linked, byLot: all.byLot }, today, opts.idle ?? 7, { readonly: plan.readonly, hasVisibleField: plan.hasVisibleField }), ...newsIssues(lots, entries, newsDir, hypothesesOf(root, plan.configFile ?? join(root, 'cadence.yaml'))), ...titles, ...gates, ...docSyncIssues(plan, root, all.byLot), ...resourceIssues(lots, root), ...(plan.hasPublicField ? missingPublicTitles(lots, entries) : []),
         ...plan.ignore.invalid.map((src) => ({ message: `ignore : motif invalide « ${src} »` }))];
     // Un plan en lecture seule se corrige avec l'outil du projet : ne pas conseiller une commande raf qui refuserait.
     return plan.readonly ? issues.map((i) => ({ ...i, message: i.message.replace(/ — raf (start|public) .*$/, '') })) : issues;
@@ -179,6 +189,7 @@ export function hypothesesOf(root, configFile) {
 /**
  * Documentation en retard (L143, clé `docs.sync`) : un lot en cours — ou terminé à partir de `docs.since` — dont les commits de
  * travail touchent des chemins sans toucher le document que la règle désigne. Les commits de plan ne comptent pas.
+ * Un lot dont l'écart est acquitté et motivé (`raf docs-ok`, L317) n'est pas compté.
  */
 export function docSyncIssues(plan, root, byLot) {
     const { sync, since } = readDocsConfig(plan.configFile ?? join(root, 'cadence.yaml'));
@@ -186,6 +197,7 @@ export function docSyncIssues(plan, root, byLot) {
         return [];
     return plan
         .lots()
+        .filter((l) => !l.docsOk)
         .filter((l) => l.status === 'doing' || (l.status === 'done' && !!since && !!l.finished && l.finished >= since))
         .flatMap((l) => docSyncGaps(sync, filesOf(root, workCommits(plan, root, byLot.get(l.id) ?? []))).map((g) => ({ message: gapMessage(l.id, g) })));
 }

package/dist/check.js

@@ -3,7 +3,18 @@ import { isOpen } from './plan.js';
 import { isRecurring } from './recurring.js';
 /** Un commit sur une ligne : sha abrégé et sujet. */
 export const short = (c) => `${c.sha.slice(0, 7)} ${c.subject}`;
-export function check(lots, linked, today, idleDays = 7) {
+/** Titre d'un lot de revue UX planifiée : « Revue UX — <écran> ». */
+const UX_REVIEW_TITLE = /^revue ux\s+—/i;
+/** Message de l'écart d'une revue UX sans `visible:` ; la correction dépend de qui tient le plan (L321). */
+function uxReviewMessage(lot, plan) {
+    const head = `${lot.id} est une revue UX (« ${lot.title.slice(0, 60)} ») sans visible: — l'étape UX n'aurait pas lieu`;
+    if (!plan.readonly)
+        return `${head} : poser visible: true dans le plan (raf visible ${lot.id} on, ou raf add --visible pour un nouveau lot)`;
+    if (plan.hasVisibleField === false)
+        return `${head} : ce plan ne porte pas visible : mapper le champ dans cadence.yaml (plan.fields.visible) si l'outil du projet l'écrit ; sans ce champ, la revue d'ergonomie de cet écran se fait hors orchestrate`;
+    return `${head} : poser visible: true dans le plan avec l'outil du projet (plan en lecture seule)`;
+}
+export function check(lots, linked, today, idleDays = 7, plan = {}) {
     const issues = [];
     const ids = new Set(lots.map((l) => l.id));
     for (const c of linked.orphans)
@@ -19,7 +30,14 @@ export function check(lots, linked, today, idleDays = 7) {
             issues.push({ kind: 'todo-with-commits', message: `${lot.id} a ${commits.length} commit(s) mais est encore todo — raf start ${lot.id}` });
         }
         if (lot.status === 'doing' && !recurring) {
-            const last = commits[0]?.day ?? lot.started;
+            // Un lot parent travaille par ses sous-lots (champ parent:, L321) : leur dernier commit, ou leur démarrage s'ils sont en cours, compte comme le sien.
+            const own = [commits[0]?.day ?? lot.started];
+            for (const sub of lots) {
+                if (sub.parent !== lot.id)
+                    continue;
+                own.push(linked.byLot.get(sub.id)?.[0]?.day ?? (sub.status === 'doing' ? sub.started : undefined));
+            }
+            const last = own.filter((d) => !!d).sort().at(-1);
             if (last && diffDays(last, today) > idleDays) {
                 issues.push({ kind: 'idle', message: `${lot.id} en cours sans commit depuis ${diffDays(last, today)} j (${lot.title})` });
             }
@@ -30,6 +48,10 @@ export function check(lots, linked, today, idleDays = 7) {
                 issues.push({ kind: 'done-open-tasks', message: `${lot.id} terminé avec sous-tâche(s) ouverte(s) : ${open.map((t) => t.id).join(', ')}` });
             }
         }
+        // L271 : sans visible:, le lot ne passe par aucune étape UX d'orchestrate (precheck → implement → review) et la revue de l'écran n'a pas lieu.
+        if (isOpen(lot.status) && UX_REVIEW_TITLE.test(lot.title) && !lot.visible) {
+            issues.push({ kind: 'ux-review-not-visible', message: uxReviewMessage(lot, plan) });
+        }
         for (const p of lot.problems)
             issues.push({ kind: 'bad-field', message: `${lot.id} : ${p}` });
         for (const d of lot.after) {