@sylad/cadence 0.10.1 → 0.12.0

package/.claude-plugin/marketplace.json

@@ -1,14 +1,27 @@
 {
   "name": "cadence",
   "description": "cadence — a repo-native working method for Claude Code sessions",
-  "owner": { "name": "Sylvain Ladoire" },
+  "owner": {
+    "name": "Sylvain Ladoire"
+  },
   "plugins": [
     {
       "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": "0.10.1",
+      "version": "0.12.0",
       "source": "./",
-      "author": { "name": "Sylvain Ladoire" }
+      "author": {
+        "name": "Sylvain Ladoire"
+      }
+    },
+    {
+      "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. No CLI needed.",
+      "version": "0.2.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": "0.10.1",
+  "version": "0.12.0",
   "author": { "name": "Sylvain Ladoire" },
   "homepage": "https://github.com/Sylad/cadence",
   "repository": "https://github.com/Sylad/cadence",

package/README.md

@@ -19,6 +19,23 @@ several projects through subagents — plus three reviewer agents: `ux-reviewer`
 gate, and `qa-reviewer`, which walks the delivered app in a real browser and
 reports a page left empty or in error.
 
+And a second plugin, [`cadence-hud`](#cadence-hud): a status band above the Claude
+Code prompt that shows the session's context, quota, cost and the orchestrate waves running.
+
+## What's new
+
+**0.12.0**: the `cadence-hud` plugin (a status band above the Claude Code prompt),
+`raf ignore` to acknowledge a commit without a lot, waves that size the review to the lot,
+hand back a lot whose deliverable is already there and start the app themselves for the UX
+review (`orchestrate.ux`), and briefs that require the README to follow the change. **0.11.0**: waves on different repositories run side by side under a shared cap of
+simultaneous sessions (`--max-sessions`, 2 by default), and every release now has its
+changelog section and GitHub release. **0.10.1**: the QA expectations file (`docs/qa/expectations.md`) is kept with the plan —
+a commit that only touches it no longer has to cite a lot. **0.10.0**: `cadence orchestrate`
+sends an already-committed lot straight to review, and sessions only ask questions that
+name what they would change.
+
+Every version, with what it brings and since when: [CHANGELOG.md](CHANGELOG.md).
+
 ## raf
 
 - The plan is a YAML file in the repo (`docs/plan/raf.yaml`), edited by the CLI.
@@ -48,7 +65,7 @@ reports a page left empty or in error.
 ```sh
 npm install -g @sylad/cadence    # or: npx -p @sylad/cadence raf …
 
-raf init                          # docs/plan/raf.yaml + post-commit hook
+raf init                          # docs/plan/raf.yaml + post-commit hook + .playwright-mcp/ in .gitignore
 raf add "Monthly dedup on merge" --estimate 2
 raf add "Typo in footer" --quickwin
 raf add "Loan cache" --after L1
@@ -65,16 +82,19 @@ raf gantt                         # docs/plan/gantt.html
 
 | Command | Effect |
 |---|---|
-| `raf init [--project name] [--prefix L] [--no-hook]` | create the plan and install the hook |
+| `raf init [--project name] [--prefix L] [--no-hook]` | create the plan, install the hook, add `.playwright-mcp/` to `.gitignore` |
 | `raf add "title" [--estimate d] [--quickwin] [--visible] [--public "title"] [--after L2,L4] [--parent L3]` | add a lot or a sub-task, print its id (`--public`: the lot's title in the public's words, written as `public:` right after `title:`) |
 | `raf add "title" --every <days>` · `raf did <id> ["text"]` | recurring lot: `every` (days) and `last` (last time done) fields; the lot stays `todo`, `raf now` and `session start` list it under « Récurrent » with « dû depuis N j » / « prochain dans N j »; `raf did` resets the count (spec: `docs/superpowers/specs/2026-10-04-L11-tache-recurrente.md`) |
 | `raf public <id> "title"` · `raf public <id> --clear` | set, replace or remove the public title of a lot |
 | `raf start <id>` · `raf done <id> [--force]` · `raf drop <id> [--reason text]` | dated transitions (`done` refuses open sub-tasks unless `--force`) |
 | `raf note <id> "text"` | dated note — keep decisions next to the work |
+| `raf show <id> [--notes]` | one lot: status, dates, `after`, public title, dated notes in order, then the counted commits (as `raf commits`); `--notes` prints the notes alone |
 | `raf commits <id>` | the commits counted for a lot (the set the code review gate uses), one `<sha> <subject>` per line, oldest first |
 | `raf now` | what to do next |
 | `raf list [--status s]` | flat list |
-| `raf check [--since date] [--idle 7]` | since the plan's adoption date by default: commits without a lot (commits touching only plan files are exempt), unknown ids, `todo` lots that already have commits, idle lots, `done` lots with open sub-tasks, bad or circular dependencies |
+| `raf ignore <sha> \| "exact subject" [--reason text]` | acknowledge a commit without a lot (tooling chore, a plan commit citing an unknown id) without rewriting history: a dated, reasoned line in the plan's `acknowledged:` section; a sha is exact, a subject covers every commit carrying it |
+| `raf check --ignored` | list the acknowledged commits with their date and reason |
+| `raf check [--since date] [--idle 7]` | since the plan's adoption date by default (a visible lot without a public title is only a `⚠` warning: it never changes the exit code): commits without a lot (commits touching only plan files are exempt), unknown ids, `todo` lots that already have commits, idle lots, `done` lots with open sub-tasks, bad or circular dependencies |
 | `raf gantt [-o file]` | standalone Gantt page |
 | `raf hook install` | add the (non-blocking, read-only) post-commit hook |
 
@@ -190,7 +210,7 @@ What changed *for the user*, one entry per visible lot, each with a screenshot.
 ```sh
 raf add "Amounts like 3.000 read as three thousand" --visible   # → L8
 raf start L8 && git commit -m "fix(L8): thousands separator" && raf done L8
-cadence news new L8          # docs/nouveautes/2026-09-29-amounts-like-3-000-….md
+cadence news new L8          # docs/nouveautes/2026-09-29-amounts-like-3-000-….md (title: the lot's public title if any)
 # add docs/nouveautes/captures/l8.png, list it under `captures:`, write the text
 cadence news check           # exit 1 on drift (also part of raf check)
 cadence news build -o frontend/public/nouveautes
@@ -219,7 +239,7 @@ captures:
 
 | Command | Effect |
 |---|---|
-| `cadence news new <lot…> [--title t]` | entry skeleton, dated and timed now (`date`, `created`), titled after the lot |
+| `cadence news new <lot…> [--title t]` | entry skeleton, dated and timed now (`date`, `created`), titled after the lot's public title (`public`), else its title; `--title` wins |
 | `cadence news list` | entries, newest first (see *Order* below) |
 | `cadence news check` | visible lots done without entry, unknown lots, missing or undeclared screenshots, entries without creation time, bad headers |
 | `cadence news stamp` | migration: writes `created:` into entries without one (or with an empty one), from the author date of the commit that added the file under its current name (now if not committed yet) |
@@ -453,6 +473,19 @@ deliver:
   deployTimeout: 1800     # seconds, per deploy command
 ```
 
+A public title (`public:`) longer than the site's Plan page accepts fails its build. Declare the limit
+in `cadence.yaml` and it is caught before the push:
+
+```yaml
+news:
+  publicTitleMax: 80      # characters; without the key, `raf check` warns at 80 in a project that has a news directory
+```
+
+`raf check` also warns (`⚠`, not an error: exit code 0 if nothing else is wrong) about every visible lot, dropped ones excepted, that has no public title: the site would show its technical title (a done lot cited by a News entry is spared: the site reuses that entry's title). Fix it with `raf public <id> "…"`.
+
+With the key, `raf public`, `raf add --public`, `raf done` (on a lot whose public title is too long) and
+`cadence news new` (its title) refuse above it; without it, only `raf check` warns.
+
 ```sh
 cadence deliver --dry-run    # preconditions, then the resolved steps; nothing runs
 cadence deliver              # 0 delivered and verified · 1 a step failed · 2 refused before acting
@@ -632,14 +665,15 @@ exception is a **formatting retry** (below).
 cadence orchestrate finance-tracker:L41 ol-companion:L22 cadence:L18@haiku
 cadence orchestrate L18                      # from inside a project
 cadence orchestrate … --budget 1.5M          # 1500000, 1.5M, 800k; default 2M
+cadence orchestrate … --max-sessions 3       # sessions running at the same moment, all waves together; default 2
 cadence orchestrate … --dry-run              # preconditions + the plan of the wave; nothing is started
-cadence orchestrate --status [<wave>]        # the table, read back from the state (default: the last wave)
+cadence orchestrate --status [<wave>]        # the live waves and the repositories they hold, then the table (default: the last wave of this folder)
 cadence orchestrate --resume [<wave>] [--budget 1M] [--answer ol-companion:L22 "reply"]
 ```
 
-You choose the lots; the order is the order given (one queue per repository, two repositories at most
-at the same time). `@haiku|@sonnet|@opus` sets the model of the implementation and corrections of that
-lot (default Sonnet; reviews are always Opus; Haiku only when you write it, for a mechanical lot). Run it
+You choose the lots; the order is the order given (one queue per repository, as many repositories at the
+same time as the session cap allows — 2 by default). `@haiku|@sonnet|@opus` sets the model of the implementation and corrections of that
+lot (default Sonnet; reviews are Opus, except the light review below; Haiku only when you write it, for a mechanical lot). Run it
 in the background and read `--status`: it prints one line per transition and the final table.
 
 **Cycle of a lot**: preconditions (clean tracked files, lot `todo` or `doing`, dependencies met) →
@@ -652,6 +686,27 @@ you with the findings. A small lot (`estimate` ≤ 0.5 or `quickwin`) gets one s
 usability (code only when the lot is not `visible`). Failing tests (reported red, or red when
 `orchestrate.test` is run) go straight to a correction.
 
+**Review sized to the lot (L108)**: a lot whose `estimate` is ≤ `orchestrate.review.threshold` (0.25 day by default)
+is *light*: one single review (Sonnet by default, `code-reviewer` agent, same criteria), no minors pass — the minors are
+returned to the lead as notes (proposals). A blocking or major finding on a light lot still triggers a correction, and
+the review that follows is the full one (Opus); the cap of two correction passes is unchanged. A bigger lot keeps the
+chain described above (Opus, two corrections, minors pass). `--dry-run` shows « revue légère » on a light lot.
+
+```yaml
+orchestrate:
+  review: { threshold: 0.25, light: sonnet, full: opus }   # defaults; threshold in days (0 = no light lot), models haiku|sonnet|opus
+```
+
+`full` is also the model of the UX review and of the single pass of a small lot that is not light.
+
+**Pre-check « deliverable already present? »** (L77). Before the first implementation of a lot that has no commit yet, a
+short read-only session (Sonnet, `precheck` step, brief `templates/orchestrate/precheck.md`) looks in the repository for
+what the lot asks for (another lot, or a correction, may have done it already). It answers `oui` (everything is there,
+with proofs), `partiel` or `non`: on `oui` no implementation session is opened and the lot is handed back
+(`livrable déjà présent : <résumé> (<preuves>)`) for the lead to drop or close it; on `partiel` the finding goes into the
+implementation brief and a warning; on `non` — or an unreadable report, which only adds a warning — the wave goes on. A
+lot that already has commits is never pre-checked (resuming it is legitimate). `orchestrate.precheck: false` turns it off.
+
 **A lot that already has commits** (a spec commit, an interrupted wave, a lot committed by hand, a lot sent back after a
 review) still starts with the implementation session: its brief tells it to read the lot, its notes and its open
 sub-tasks, which carry the findings of any earlier review. If that session ends without a new commit on a lot that
@@ -674,13 +729,40 @@ review with minors: it concludes on that review instead of staying suspended.
 
 **Choices, not questions**: the author brief tells the session to decide minor interpretation questions itself and to list them under `choix` in its report; the reviewer receives that list to re-read, and the final table prints each one (`choix fait : …`). A session stops with a question only on a real blocker: a decision that changes the scope or the architecture or is costly to undo, AND that the plan, its notes and CLAUDE.md do not settle; everything else is a choice.
 
+**Frozen copy of the tool (L61)**: at the real start of a wave (not with `--dry-run` or `--status`), cadence copies the
+parts of its package that run the wave (`bin/`, `dist/`, `templates/`, `agents/`, `skills/`, `package.json`; `node_modules`
+is linked, not copied) into `.cadence/runs/<wave>/tool/` and relaunches the orchestrate process from that copy (the
+parent process waits, relays the signals and exits with the same code or signal). Code, brief templates and agents
+therefore come from the snapshot: a wave can orchestrate cadence itself, and a session of the wave may edit
+`templates/` or rebuild `dist/` without touching the wave running. `--resume` relaunches from the snapshot of the
+resumed wave, never from the current `dist/`; a wave without a snapshot (started before L61) resumes with the current
+package and a warning. The copy is removed with the wave folder. The wave's pid in `--status` is the relaunched process.
+The sessions of the wave also get `.cadence/runs/<wave>/tool/bin` (the `raf` and `cadence` entries of the snapshot) **first in their
+`PATH`**, ahead of the per-project Node below and of the usual `PATH`: the `raf` a reviewer runs (`raf commits`…) is the
+snapshot's, not the installed one. A wave without a snapshot leaves the `PATH` as it is.
+
 **What stays with you**: choosing the lots, the questions raised (`--resume --answer`), re-verifying
 after the wave (`git log`, tests, `raf check`), `raf done`, **`raf ux`** (the orchestrator reports the UX
 verdict and screenshots, it does not record it), the push and the deliveries, one project at a time.
 
-**Guards, imposed by the code**: at most two sessions, one per repository (a lock in the repository's
-shared state, `orchestrate.lock`, which also makes `cadence deliver` refuse that repository) and one wave
-per folder; `Agent`, `git push`, `cadence deliver`, `raf done|review|ux` are denied to the sessions; a
+**Several waves at once**: the lock is per **repository** (a lock in the repository's shared state,
+`orchestrate.lock`, which also makes `cadence deliver` refuse that repository), not per folder. A wave is
+refused only when one of its repositories is held by a live wave (`<repo> : une orchestration y est déjà en
+cours`; the lock of a dead process is detected and cleared); two waves on different repositories run side by
+side, even when started from the same parent folder. They share a **cap on simultaneous sessions**, counted
+across all live waves: 2 by default, `--max-sessions N` (or `CADENCE_MAX_SESSIONS=N`) to change it — give
+every wave the same value: each wave counts ALL live sessions, whatever their slot, and waits while that
+count has reached ITS OWN cap, so with different caps the highest one can push the total past the lowest
+(which then waits). A session that finds no free slot **waits** (the wave is not refused; the journal says
+`en attente d'un créneau de session depuis …`, repeated every minute, then `créneau de session obtenu après …`).
+A slot or a registry entry is owned by a pid **and** its start time: a reused pid is a dead owner. Wave
+identifiers are reserved atomically (`-2`, `-3` suffix when two waves start in the same minute; an existing
+`--wave` is refused). The registry of live waves and the slots live under `~/.cadence/orchestrate/` (`CADENCE_HOME`
+to move it): `cadence orchestrate --status` lists, from any folder, the live waves, the repositories each
+holds, the cap of each wave and the slots in use.
+
+**Guards, imposed by the code**: a global cap of simultaneous sessions, one wave per repository at
+a time (above); `Agent`, `git push`, `cadence deliver`, `raf done|review|ux` are denied to the sessions; a
 temporary `pre-push` hook, installed for the duration of the wave and removed at its end, refuses any push
 from a session (`CADENCE_ORCHESTRATED` is in their environment; a repository that already has another
 `pre-push` hook is refused before anything starts — `pushurl` is never touched); after every session the
@@ -689,7 +771,9 @@ tree is an incident that stops the wave. `raf done|ux|review` and `cadence deliv
 `CADENCE_ORCHESTRATED` is set.
 
 **Budget**: the wave counts input + cache writes + output tokens (default 2 M); cache reads are kept and
-shown apart. When the budget (or the usage limit) is reached no new session starts, the running ones
+shown apart. Each lot also has its own budget derived from its estimate (400 k tokens per day, floor 200 k, shown by
+`--dry-run`): a lot that spent it gets no further session and is handed back to the lead, the wave budget stays for
+the others. When the budget (or the usage limit) is reached no new session starts, the running ones
 finish, the wave is *suspended* (exit code 3) and `--resume --budget …` continues. A session that returns
 nothing readable, times out (45 min for work, 25 for a review) or fails is not retried; the lot is handed
 back with the cause. Exit codes: 0 every lot ready · 1 at least one lot handed back (question, failure,
@@ -704,18 +788,23 @@ retry count in the wave budget and in the step (`formatRetry: true`); if the out
 the step fails as usual — never a second retry.
 
 State is in `.cadence/runs/<wave>/` of the folder where the command is run (added to `.git/info/exclude`
-when that folder is in a repository): `wave.json`, one `<project>--<lot>.json` per lot (steps, tokens
+when that folder is in a repository; `.cadence/` and `.playwright-mcp/`, where the Playwright MCP writes its
+output, never count as a dirty repository, even when `.gitignore` does not list them): `wave.json`, one `<project>--<lot>.json` per lot (steps, tokens
 kept apart, session ids, commits, verdicts), the JSON output of every session and a `journal.log`. After a
 cut (Ctrl-C, WSL closed) `--resume` replays an interrupted step entirely in a new session whose brief
 lists the commits already present; finished steps are never replayed.
 
 Briefs are the templates of `templates/orchestrate/` (`implement.md` is the `lead` skill's standard
-brief; `--dry-run` writes the rendered ones). A project can declare, in `cadence.yaml`:
+brief; `--dry-run` writes the rendered ones). The `implement` brief of a `visible` lot also carries the
+News instruction (`cadence news new <lot>`, factual user-side text, a screenshot in `docs/nouveautes/captures/` or
+`nocapture:`, `cadence news check` green); the brief gives the absolute path of the wave's Playwright output directory and the `implement` session gets `--add-dir` on it, to copy the capture into the repository; a lot that is not `visible` gets nothing. A project can declare, in `cadence.yaml`:
 
 ```yaml
 orchestrate:
   test: npm test                         # run by the orchestrator after a work step (optional)
-  ux: http://localhost:4200              # a URL, a launch command, or { url, command } — for the UX review
+  build: npm run build                   # run after the tests; both results go to the reviewer, who does not redo them (optional)
+  precheck: true                         # default: before the first implementation of a lot with no commit, a read-only Sonnet session checks whether the deliverable is already in the repository (see below); false skips it
+  ux: http://localhost:4200              # a URL, a launch command, or { command, url, timeout? } — for the UX review (see below)
   permissionMode: auto                   # default
   addDirs: [/home/me/projects/tmp]       # extra directories the sessions may use
   timeouts: { implement: 45, review: 25 }   # minutes
@@ -724,9 +813,80 @@ orchestrate:
   verdict: python3 scripts/raf.py note {lot} "revue de code : {verdict}"
 ```
 
+**`orchestrate.ux`, who starts the app**: a string is a URL if it starts with `http://` or `https://`, a launch
+command otherwise; both forms behave as before (the `ux` brief gives the URL, or tells the session to start the app
+with the command and stop it). The object form `{ command, url, timeout? }` makes **the program** start the app, not
+the UX session. Before the `ux` step (and before the `review-small` single pass of a small `visible` lot, which follows
+the same rule) the orchestrator:
+
+0. takes a lock on the `host:port` of `url` (a file `cadence-ux-<host>-<port>.lock` in the OS temp folder, created
+   exclusively, containing the pid of the orchestrator; a lock whose pid is dead is taken over). Another wave — in
+   this process or another — that declares the same URL waits for it, and the wait counts in `timeout`; past it the
+   note is « UX non vérifiée : url tenue par une autre vague » and nothing is started. The lock is given back after
+   the app is stopped. Declaring **distinct ports per project** is still recommended: the lock serialises two waves
+   on one URL, it does not make them fast;
+1. probes `url`; if it already answers it does **not** start anything, notes « port occupé » (`uxNote`: the UX is not
+   verified) and the lot goes on;
+2. starts `command` with `sh -c` from the repository root, in its own detached process group, its output in
+   `<wave>/<project>--<lot>/ux-app.log` (the command carries its own prefixes, e.g. `cd web && PORT=4300 npm start`;
+   there is no `env`, `cwd` or account/PIN key);
+3. probes `url` until an HTTP status below 500, for `timeout` seconds (default 300); the answer only counts while
+   the process group it started is still alive. A command that exits early, or
+   no answer in time, means « UX not verified » with the end of the log in the note: the UX session is skipped,
+   the lot goes on to the code review — it is never a failure of the wave (the single pass of a small lot still runs,
+   on the code alone, its brief saying the app could not be verified);
+4. gives the session « The running app is at `<url>` », with no instruction to start anything;
+5. at the end of the step — success, error or SIGTERM of the wave — kills the group: SIGTERM, then SIGKILL after 10 s.
+
+```yaml
+orchestrate:
+  ux: { command: 'cd web && PORT=4300 npm start', url: 'http://localhost:4300', timeout: 120 }
+```
+
+In the object form `url` must start with `http://` or `https://`, and `timeout` is only accepted together with both
+`command` and `url` (the program only waits when it starts the app). A wave stopped (incident, quota, budget) before
+the step suspends the lot without starting the app.
+
+**Node per project (`.nvmrc`)**: when a project has a `.nvmrc` at its root, every session the
+orchestrator launches for it (implementation, UX and code reviews, corrections) runs with the matching Node
+first in its `PATH`, so `node`, `npm` and `npx` resolve to it (Astro needs 22 while the default may be 20) — and so does
+the app the program starts for the UX review (`ux.command`): same links directory first in its `PATH`, no
+`. ~/.nvm/nvm.sh && nvm use` prefix needed (it exits with code 3 under `sh`). Only
+those four names (`node`, `npm`, `npx`, `corepack`) are exposed, through symlinks in
+`.cadence/runs/<wave>/node-bin/<version>/` (recreated at start and at every `--resume`): the rest of that Node's
+`bin` (globally installed `raf`, `cadence`, `claude`…) is never exposed, so it does not shadow the tools in the usual `PATH`;
+only the snapshot's `tool/bin` (above) comes first, ahead of this Node directory. `--resume` resolves
+the `.nvmrc` again for every live lot and refuses it like at start if it can no longer be resolved.
+The file is read trimmed (`22`, `v22`, `22.22`, `v22.22.3`); the highest matching version installed under
+`$NVM_DIR/versions/node` (default `~/.nvm/versions/node`) **that has an executable `bin/node`** is used: a higher
+version with an empty or broken `bin` is skipped for a lower valid one (and `--dry-run` says so); if none is valid
+the lot is refused. Only the sessions' environment changes,
+never the orchestrator's own. No `.nvmrc` → nothing changes. A `.nvmrc` that cannot be resolved (`lts/*`, an
+alias, a version not installed) refuses the lot before anything is started (exit 2), naming the requested
+version and the folder searched — there is no silent fallback to the default Node. `--dry-run` prints
+`node : v22.22.3 (.nvmrc 22)` under each lot that has one, with the skipped versions when it happens
+(`node : v22.9.0 (.nvmrc 22 ; v22.22.3 écartée : pas de node exécutable)`).
+
+**Minimal MCP servers per step**: every session the orchestrator launches gets `--strict-mcp-config --mcp-config
+<file>`, with the file written by the orchestrator in the lot's folder of the wave
+(`.cadence/runs/<wave>/<project>--<lot>/mcp-<step>.json`). `--strict-mcp-config` makes `claude` ignore every other
+source (user, project, plugin servers: Serena, context7, Cloudflare…), so a session no longer starts a handful of
+`npx`/`uvx` servers it does not use. `review` and `review-recheck` always get an empty set
+(`{"mcpServers":{}}`); so do `implement`, `fix` and `fix-minors` on a lot without a screen. Playwright, launched as
+`npx -y @playwright/mcp@latest --output-dir <wave>/<project>--<lot>/playwright`, is loaded for the `ux` step and, on a
+`visible` lot, for `implement` and `fix` (`fix-minors` included) and, on a small `visible` lot, for `review-small` (its only
+usability review; `review-small` of a small lot without a screen loads nothing), so the screenshots and snapshots of the work and of
+the review stay with the wave, outside the repository, where the lead can look at them; the final table prints that
+folder whenever Playwright was loaded for the lot, even if no `ux` step ran
+(`<project>:<lot> — captures Playwright : <dir>`; `uxCaptures` in the wave state). The `implement`, `fix`,
+`fix-minors`, `review-small` and `ux` briefs tell the session to give relative file names if a Playwright server is available, and
+otherwise to keep any Playwright CLI output outside the repository.
+`--dry-run` prints, under each step, `mcp : aucun` or `mcp : playwright (…)`. There is no per-project override in
+`cadence.yaml` yet.
+
 Without `start`, a read-only plan's `todo` lot is refused (start it with the project's tool); without
 `verdict`, the review verdict stays in the wave's state and you report it. Only the plan's files
-(`plan.path`, `plan.files`, the QA expectations file) are committed from those commands; anything else dirty stops the lot.
+(`plan.path`, `plan.files`, the QA expectations file) are committed from those commands; anything else dirty stops the lot (`.cadence/` and `.playwright-mcp/` excepted, as above).
 
 ## Claude Code skills
 
@@ -763,7 +923,7 @@ repository with `cadence skills install` (to `.claude/skills/cadence-*` and
 - **lead**: from a folder holding several projects, one subagent per project
   gathers the facts, you choose the priorities, the lots are delegated with
   `cadence orchestrate` (fresh short sessions with a standard brief — test first,
-  commits citing the lot, no push — reviewed by the `code-reviewer` agent, see
+  README and usage documentation updated with the change, commits citing the lot, no push — reviewed by the `code-reviewer` agent, see
   [orchestrate](#orchestrate)), re-verified by the lead, then delivered
   one project at a time; a delivery that changes what a page shows or what it is
   served is then checked in the running app by the `qa-reviewer` agent, whose
@@ -780,7 +940,8 @@ repository with `cadence skills install` (to `.claude/skills/cadence-*` and
   block, dead code) or a named rule, each with `file:line` and a concrete
   scenario; real defects only, ranked, what it could not verify, and a one-line
   verdict for `raf review`. It takes the lot's commits from `raf commits`, never
-  runs a build whose output is used live, and never edits code.
+  runs a build whose output is used live, and never edits code. A README or usage
+  documentation that does not follow the lot's change is a *major* finding.
 - **qa-reviewer** (agent): any web app; given a repository and a base URL (and
   optionally a lot id, to start with the pages it touched — for a backend-only
   lot, those that call the changed endpoints), it opens each page of
@@ -796,19 +957,56 @@ repository with `cadence skills install` (to `.claude/skills/cadence-*` and
   N/N, follow-ups as `raf add` lines, what it could not verify, a one-line
   verdict. Read-only: GET only, no login, nothing submitted; it stops at a PIN.
 
+## cadence-hud
+
+A band above the Claude Code prompt (terminal and desktop app), refreshed every 5 s:
+
+```
+ctx ▰▰▰▰▱▱▱▱▱▱  42 % 84k/200k  │  5h  23 % ↻ 2 h 10  │  7j  61 % ↻ 6 j 15 h  │  $1.23  │  fable 410k $0.95 · sonnet 85k $0.12  │  ⚙ 2 agents
+⟳ cadence · 2026-10-07-2131 en cours  │  budget ▱▱▱▱▱▱▱▱▱▱   1 % 14k/2M  │  1 session/2
+  L112  implémente  implement@sonnet 34 s         global-setup coupe le cache de compilation de Node…
+```
+
+Context of the session (green / orange / red at 50 and 75 %), the 5-hour and 7-day quota
+windows with the time to their reset, the cost of the session and its split per model, the
+subagents of this session, and every live `cadence orchestrate` wave: budget, sessions, one
+aligned line per active lot (status, step, model, elapsed, start of the title), the lots still
+waiting. When no wave is running, the last finished one stays on a grey line until the next
+starts. Waves are read from disk (`~/.cadence/orchestrate/waves/`, then `.cadence/runs/`); no
+cadence command is run, and the CLI is not required.
+
+Install it as a plugin from the same marketplace:
+
+```
+/plugin marketplace add Sylad/cadence
+/plugin install cadence-hud@cadence
+```
+
+`/hud` hides or shows the band. The source lives in [`plugins/cadence-hud`](plugins/cadence-hud/README.md)
+(its own README has the details of every cell); it is not part of the npm package. To work on it:
+`claude plugin validate plugins/cadence-hud`, `claude plugin test plugins/cadence-hud`, and
+`tsc -p plugins/cadence-hud` once Claude Code has loaded the plugin at least once (it generates
+the `.claude-plugin/types` the tsconfig extends).
+
 ## Releasing
 
 A version exists in three places and is published in two; a release does all of it, in this order:
 
 1. Bump `version` in `package.json` (then `npm install` to refresh `package-lock.json`),
    `.claude-plugin/plugin.json` and `.claude-plugin/marketplace.json`, in the commit that closes the lot.
+   Write the version's section of `CHANGELOG.md` (`## [x.y.z] - date`, what changes for the user, lots cited)
+   and refresh the « What's new » summary of this README in that same commit.
 2. `git tag v<version> && git push origin main v<version>` — the tag starts `.github/workflows/publish.yml`,
    which publishes to npm through Trusted Publishing (OIDC, no token stored anywhere): it checks the tag
-   matches `package.json`, `.claude-plugin/plugin.json` and `.claude-plugin/marketplace.json`, then `npm publish --provenance`, where `prepublishOnly` runs the type-check and the
-   tests and `prepare` builds `dist/`; a red suite stops the publication. The trusted publisher is declared
+   matches `package.json`, `.claude-plugin/plugin.json` and `.claude-plugin/marketplace.json` and that `CHANGELOG.md` has a `## [x.y.z]` section for it (no section, no publication), then `npm publish --provenance`, where `prepublishOnly` runs the type-check and the
+   tests and `prepare` builds `dist/`; a red suite stops the publication; then it creates the GitHub release with that CHANGELOG section as its text. The trusted publisher is declared
    once on npmjs.com (package settings → Trusted Publisher → GitHub Actions, `Sylad/cadence`, `publish.yml`).
 3. Watch the run: `gh run watch` (or `gh run list --workflow publish.yml`).
 4. Check the effect: `npm view @sylad/cadence version` answers the new version.
+   A run is safe to re-run, and two runs for one tag queue instead of racing (`concurrency` per ref, never cancelling the one that publishes):
+   a version already on npm skips `npm publish`, and a GitHub release that is missing is created (`--verify-tag`)
+   while an existing one is left alone. If the package is on npm but the release is still missing, re-run the job;
+   the by-hand fallback is `gh release create v<version> --title v<version> --notes-file <the section of CHANGELOG.md> --verify-tag`.
 
 The Claude Code plugin is read from the repository, so pushing `main` is what updates it; npm is what
 `npx @sylad/cadence` and a global install read, and only the tag publishes there. A missing tag, or a red

package/agents/code-reviewer.md

@@ -35,7 +35,8 @@ fact. If the path or the id is missing, or the lot has no commit to review, say
    and a finding must point at a line that exists today. Read what the changed code calls and what
    calls it, far enough to know whether a caller is broken.
 5. **Run what verifies**: the project's tests, type check and linter, with the commands found in
-   step 1. A linter or coverage tool the project does not have goes under "not verified": it is
+   step 1. When the brief says the program already ran the tests and the build, take those results as given: do not rerun them
+   (nor rebuild), and run only a check they do not cover. A linter or coverage tool the project does not have goes under "not verified": it is
    not a finding. Do not run a command that deploys, publishes, pushes, migrates data or reaches a
    remote system, and never run a build whose output directory is used live — the hint is an
    output directory that a `bin` entry or a symlink on the PATH points to; list what you did not
@@ -56,14 +57,17 @@ fact. If the path or the id is missing, or the lot has no commit to review, say
    - errors swallowed, inputs trusted, resources not released, secrets or personal data written
      to a log or to the repository;
    - a written convention of the project not followed: quote the line of CLAUDE.md.
+   - documentation that does not follow the change: the lot changes a behaviour, a command, an option or a default and the README (or the project's usage documentation) still describes the old one or says nothing: name the file and the stale or missing passage.
 7. **Rank** each finding: *blocking* (wrong result, lost data, security hole, crash, a command that
    fails), *major* (breaks in a plausible scenario, behaviour changed without a test, a written
-   convention broken), *minor* (costs maintenance: duplication, dead code). Untested code that is
+   convention broken, a README or usage documentation that does not follow the change), *minor* (costs maintenance: duplication, dead code). Untested code that is
    practically unreachable, and a rule that holds as written while an edge defeats its purpose, are
    *minor* — unless they can lose or corrupt data.
 
 ## Output
 
+A proposed sub-task describes an observable bug (a wrong output, a crash, a measured regression); any other minor finding stays a note of this lot, not a sub-task.
+
 A short report:
 
 - **Commits reviewed**: sha and subject, and the commands you ran with their result (counts).
@@ -85,5 +89,6 @@ A short report:
 - Judge on taste: naming, formatting or structure you would have written differently is not a
   finding unless a written convention or a named practice says so.
 - Report a finding you have not read in the code or measured, or pad the list: real defects only.
-- Take the author's summary, or a green run you did not launch, as proof.
+- Take the author's summary, or a green run you did not launch, as proof — except the results the
+  brief says the program ran itself.
 - Edit code, commit, or record `raf review` yourself: the session that owns the lot does it.

package/agents/precheck-reader.md

@@ -0,0 +1,14 @@
+---
+name: precheck-reader
+description: Read-only pre-check reader. Before a lot that has no commit is implemented, looks in the repository for a deliverable that another lot or a correction already made, and reports oui, partiel or non with a proof (file:line or commit sha) for each part. Quick look only, it implements nothing, runs no test suite and does not review. Used by the orchestrator, not by hand.
+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.
+
+- 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.
+- Answer `oui` only when every part is present, each with a proof; `partiel` when some are (say which); `non` otherwise. When in doubt, answer `non`.
+- Give the report in the structured output the brief asks for.

package/agents/qa-reviewer.md

@@ -42,7 +42,7 @@ missing, or the URL does not answer, say so and stop.
    write it into the repository. Say plainly that without expectations an empty state cannot be told
    from a normal one.
 4. **Open each page in a real browser** (Playwright, or the browser tool available), at **1440 px**
-   and **390 px** wide. Let it settle: after `load`, wait a fixed few seconds, scroll through the
+   and **390 px** wide. Walk within the bounded pass below. Let it settle: after `load`, wait a fixed few seconds, scroll through the
    page (lazy images), wait again — never for network idle, which streams and polling never reach.
    Then measure:
    - browser state, once before the first page, in a profile already used (a persistent context, not a fresh one — a `userDataDir` reserved for QA and kept between passes, never the user's own browser profile): compare the bundle the page loaded (its script URL) with the one `index.html` references, re-read without cache — a returning visitor still holds the old one, so a difference is stated in the report — then clear the cache and measure;
@@ -95,6 +95,23 @@ missing, or the URL does not answer, say so and stop.
    false, or an error is shown to the user), *major* (secondary content missing or wrong, a section
    silently dropped after a failed or empty API call, a broken content image), *minor* (noise). A broken line of the expectations with no visible loss on the page (the content is on screen by another path) is *minor* too.
 
+## Bounded pass
+
+The pass has a time budget: the one the caller names, otherwise 15 minutes. You keep the count
+from the first page.
+
+- Never wait in silence on your own background work (a scripted walk, a long browser task, a
+  listener): every wait has a timeout and is announced in one line (what you wait for, until
+  when). A task still running at its deadline is stopped and its pages counted as partial or not
+  reached — you do not wait for it again.
+- Write as you go. After each width measured, append its measurements to a results file in the
+  temporary directory — one line per page and width, the page and the width named — before
+  measuring the next. Never one single file written at the end of the pass: a pass that is
+  stopped loses it all, and a page stopped between its two widths keeps the first.
+- When the budget is spent, or the caller asks you to stop, stop walking and write the report from
+  the results file: pages measured at both widths are checked, a page measured at one width is
+  partial, the pages not reached are named, never dropped.
+
 ## Output
 
 A short report:
@@ -102,7 +119,7 @@ A short report:
 - **Pages checked N/N**, with the base URL and the date and time of the run, and the two widths. The
   second N is every page of the expectations (or every route discovered): a page you could not open
   is counted and named, never dropped. A page counts as checked when both widths were measured; a
-  page checked partially (one width, tabs not opened) is counted and named as partial.
+  page checked partially (one width, tabs not opened) is counted and named as partial. If the pass stopped before the end (budget spent, stop requested), say so in the first line, with the pages measured so far.
 - **Findings**, most severe first, each with: the route, its kind and rank, what was expected —
   quote the line of the expectations, or name the universal check, or, for a suspect, give the
   expectation line you propose —, what was measured, and the evidence — status code, response

package/agents/ux-reviewer.md

@@ -38,7 +38,7 @@ A short report:
   "not compliant: 1 blocking".
 - **Findings**, most severe first, each with: what (with the capture), the rule or the measure, the
   proposed change, the effort (S ≤ a session, M ≈ a day).
-- **Proposed sub-tasks**: one `raf add --parent <lot> "…"` line per finding worth doing.
+- **Proposed sub-tasks**: one `raf add --parent <lot> "…"` line per finding worth doing. A proposed sub-task describes an observable bug (a wrong output, a crash, a measured regression); any other minor finding stays a note of this lot, not a sub-task.
 - For any redesign, a **described mockup** (layout, hierarchy, what moves where) to be approved before
   anyone codes it.
 

package/bin/cadence.js

@@ -34,8 +34,9 @@ if (tool === 'raf') {
   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
-  cadence orchestrate <projet>:<lot>[@modèle]… [--budget 2M] [--dry-run]
-                    une session claude neuve par étape (implémentation, revues, corrections) ; --status, --resume
+  cadence orchestrate <projet>:<lot>[@modèle]… [--budget 2M] [--max-sessions 2] [--wave id] [--dry-run]
+                    une session claude neuve par étape (implémentation, revues, corrections) ; --status, --resume ;
+                    --max-sessions : sessions simultanées, toutes vagues confondues (CADENCE_MAX_SESSIONS)
   cadence skills install [--dir .claude] [--force]
                     installe les skills Claude Code session-start, session-close, deliver et l'agent ux-reviewer`);
   process.exitCode = !tool || ['help', '--help', '-h'].includes(tool) ? 0 : 2;