@sylad/cadence 0.20.0 → 0.22.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": "0.20.0",
+      "version": "0.22.0",
       "source": "./",
       "author": {
         "name": "Sylvain Ladoire"
@@ -16,8 +16,8 @@
     },
     {
       "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.3.4",
+      "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.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.20.0",
+  "version": "0.22.0",
   "author": { "name": "Sylvain Ladoire" },
   "homepage": "https://github.com/Sylad/cadence",
   "repository": "https://github.com/Sylad/cadence",

package/README.md

@@ -24,7 +24,7 @@ Code prompt that shows the session's context, quota, cost and the orchestrate wa
 
 ## What's new
 
-**0.20.0**: `cadence-hud` no longer misleads once the work is over: `/hud cmd` lists the background commands it counts (id, tool, origin, age, name), any other argument answers `argument inconnu` instead of hiding the band, commands with no end seen for an hour or no record go to a grey `N cmd sans fin vue`, a finished subagent takes its commands with it, two races that left a `1 cmd` counted forever are closed, and a finished wave shows grey without its budget then disappears after 30 minutes (L142); the `qa-reviewer` and `ux-reviewer` agents are read-only for real, their frontmatter listing Read, Grep, Glob, Bash and the Playwright tools (L140). **0.19.1**: `cadence-hud`'s `N cmd` counter goes back down when a Monitor expires, when the background commands a subagent started end with it, and at session start or plugin reload (L135); its `tool.call` and `prompt.submit` guard hooks carry a `.catch` on registration, which clears the `claude plugin validate` warning (L136). **0.19.0**: `cadence orchestrate` lifts a repository's lock and `pre-push` guard as soon as every lot of the wave that touches it is finished, so `cadence deliver` works there while the wave continues elsewhere (L132); a review that leaves a repository dirty hands back that lot only, suspends the lots still queued in that repository and keeps the other repositories running, its verdict reported instead of lost (L133); `cadence session close` re-run without a `session start` keeps the window since the last opening (L131); `cadence-hud` draws the lot rows of a wave in aligned columns on every surface (L134). **0.18.0**: `cadence session next` prints what it records (issue #6); `cadence session close` covers the period since the last `session start` (or the last close) and says so in its title, `--since` still wins (issue #7). **0.17.0**: `cadence-hud` shows an `N cmd` segment next to the agents, the background commands of the session (Bash run in the background and Monitor, subagents' included), tracked from the tool results and ended by the task's notification or `TaskStop`. **0.16.0**: a lot can declare **neighbouring repositories** (`repos:` key of the lot, `{ path, cite }` for a repository shared between projects): `cadence orchestrate` refuses, locks and guards them, gives them to every session as `--add-dir`, and `raf commits`, `raf show` and the review verdict read the commits that cite the lot there too. **0.15.0**: `hook.autostart` in `cadence.yaml` (`warn` by default, `refuse` or `start`): a pre-commit hook that refuses, or starts in the same commit, a lot still todo that the commit cites; `cadence session start|close --all [--depth n]`, one section per project under a folder. **0.14.0**: `cadence lead tour`, the lead's morning table of every project in a folder, printed by a program (one line per project: lots in progress, gaps, last notes, next ready lot, repository) in place of one subagent per project; the `lead` skill calls it. **0.13.1**: `cadence-hud` takes back the segments that fit once a big one has dropped (reset times, then the per-model consumption, now short: `opus 1.2M sonnet 800k`); `CADENCE_HUD_AMBIGUOUS=1` for a terminal that draws `▰ ▱ ⚙ │ ↻` in one cell. **0.13.0**: `cadence orchestrate --status --watch` (a wave's table redrawn in the terminal, which
+**0.22.0**: `cadence orchestrate --continue` draws the next ready lot of the plan itself, in the declared priority, until the budget, the time window or a question stops it (L147); `cadence session context` prints the context of the session, which the `cadence-hud` band publishes, and the `lead` skill chains lots without the human while it stays under 60 % (L148); the band shows the progress of each project's plan, and `cadence lead tour --json` gains `progress` (L149, `cadence-hud` 0.4.0); the final review of a lot is always played, the lot's own budget bounding the writing passes only, with 65 k tokens reserved for it (L145); the cause « tests rouges après … » names the pass whose tests were red (L151). **0.21.0**: `cadence orchestrate --status` and `cadence lead tour` print the free session slots, which the `lead` skill reads (L141); `orchestrate.effort` sets the effort level of each pass of a wave (L137); `docs.sync` makes `raf check`, `lead tour` and the review brief report a document that does not follow the code (L143); `docs.articles` opens, after a green `cadence deliver`, a lot `Article <project> à rafraîchir` in the neighbouring repository (L144). **0.20.0**: `cadence-hud` no longer misleads once the work is over: `/hud cmd` lists the background commands it counts (id, tool, origin, age, name), any other argument answers `argument inconnu` instead of hiding the band, commands with no end seen for an hour or no record go to a grey `N cmd sans fin vue`, a finished subagent takes its commands with it, two races that left a `1 cmd` counted forever are closed, and a finished wave shows grey without its budget then disappears after 30 minutes (L142); the `qa-reviewer` and `ux-reviewer` agents are read-only for real, their frontmatter listing Read, Grep, Glob, Bash and the Playwright tools (L140). **0.19.1**: `cadence-hud`'s `N cmd` counter goes back down when a Monitor expires, when the background commands a subagent started end with it, and at session start or plugin reload (L135); its `tool.call` and `prompt.submit` guard hooks carry a `.catch` on registration, which clears the `claude plugin validate` warning (L136). **0.19.0**: `cadence orchestrate` lifts a repository's lock and `pre-push` guard as soon as every lot of the wave that touches it is finished, so `cadence deliver` works there while the wave continues elsewhere (L132); a review that leaves a repository dirty hands back that lot only, suspends the lots still queued in that repository and keeps the other repositories running, its verdict reported instead of lost (L133); `cadence session close` re-run without a `session start` keeps the window since the last opening (L131); `cadence-hud` draws the lot rows of a wave in aligned columns on every surface (L134). **0.18.0**: `cadence session next` prints what it records (issue #6); `cadence session close` covers the period since the last `session start` (or the last close) and says so in its title, `--since` still wins (issue #7). **0.17.0**: `cadence-hud` shows an `N cmd` segment next to the agents, the background commands of the session (Bash run in the background and Monitor, subagents' included), tracked from the tool results and ended by the task's notification or `TaskStop`. **0.16.0**: a lot can declare **neighbouring repositories** (`repos:` key of the lot, `{ path, cite }` for a repository shared between projects): `cadence orchestrate` refuses, locks and guards them, gives them to every session as `--add-dir`, and `raf commits`, `raf show` and the review verdict read the commits that cite the lot there too. **0.15.0**: `hook.autostart` in `cadence.yaml` (`warn` by default, `refuse` or `start`): a pre-commit hook that refuses, or starts in the same commit, a lot still todo that the commit cites; `cadence session start|close --all [--depth n]`, one section per project under a folder. **0.14.0**: `cadence lead tour`, the lead's morning table of every project in a folder, printed by a program (one line per project: lots in progress, gaps, last notes, next ready lot, repository) in place of one subagent per project; the `lead` skill calls it. **0.13.1**: `cadence-hud` takes back the segments that fit once a big one has dropped (reset times, then the per-model consumption, now short: `opus 1.2M sonnet 800k`); `CADENCE_HUD_AMBIGUOUS=1` for a terminal that draws `▰ ▱ ⚙ │ ↻` in one cell. **0.13.0**: `cadence orchestrate --status --watch` (a wave's table redrawn in the terminal, which
 stops with the wave) and the lead skill that names the wave and follows its journal; lot ids with `/`
 (sub-tasks of a read-only plan) accepted by `orchestrate`; `cadence-hud`'s first line measured in
 terminal cells and kept to ASCII; `publish.yml` on the v5 actions. **0.12.0**: the `cadence-hud` plugin (a status band above the Claude Code prompt),
@@ -341,6 +341,64 @@ lot in each neighbour (the one `raf commits` lists last: it cites the lot, falls
 neighbour has none), and refuses to record when a listed repository cannot be read. `raf check` does not audit the
 neighbours: their staleness is not checked, only the project's own commits are.
 
+### Documentation that follows the code
+
+A stale README misleads. `cadence.yaml` can declare which documents must follow which code:
+
+```yaml
+docs:
+  sync:
+    - paths: [src/**, bin/*.js]        # what changes…
+      docs: [README.md, docs/usage.md]  # …must change one of these, in the same lot
+    - paths: [templates/]
+      docs: [CLAUDE.md]
+    - paths: [frontend/src/**, '!**/*.test.tsx']   # a pattern starting with ! leaves files out
+      docs: [README.md]
+  since: 2026-10-09                    # optional: also audit lots finished on or after this day
+```
+
+A pattern is an exact path, with `*` (inside a folder), `**` (across folders), `?`, or a trailing `/` for
+a whole folder. `raf check` takes the **work commits** of every lot in progress (plan-only commits do
+not count; a lot finished on or after `docs.since` is audited too) and, for each pair, reports the lot when
+those commits touch `paths` without any of them touching a file of `docs`:
+
+```
+✗ L7 : documentation en retard — src/a.ts, src/b.ts sans toucher README.md ou docs/usage.md (docs.sync)
+```
+
+It counts as drift: exit code 1, shown in the `dérive` column of `cadence lead tour`, and the review
+brief of `cadence orchestrate` (`review` and `review-small`) carries the list the program computed,
+to be reported as one **major** finding per line — a stale document is not left to the reviewer's
+memory of a sentence. Touching a document is what the program checks; whether its text is true is
+still the review's reading. The commits of neighbouring repositories (`repos:`) are not audited.
+
+#### An article elsewhere that follows the delivery
+
+A case study that lives in a neighbouring repository (the project's article on a showcase site) goes stale
+the same way. `docs.articles` names it:
+
+```yaml
+docs:
+  articles:
+    - repo: ../claude-code-codex          # neighbouring repository, relative to the project
+      file: src/pages/cas/demo.md         # the article in it
+      name: demo                          # optional: the name in the lot title (default: the plan's project)
+```
+
+After a **green** `cadence deliver`, for the lots it lists as delivered **that have a public title** (`public:`, or
+the title of their Nouveautés entry), cadence opens in this repository's plan the lot
+`Article demo à rafraîchir` (todo, estimate 0.5, `repos: [{ path: ../claude-code-codex, cite: demo }]`), with a note
+that quotes the delivery, the public titles delivered, the article and the **sections to read again**: the headings
+(`#` lines, or `<h1>`…`<h6>` of an Astro page) that share a word of five letters or more with a delivered title,
+else all the `##` headings. The lot is then played like any other, in an ordinary wave (`cadence orchestrate`: an
+implementer rewrites the article in the neighbouring repository, the review checks it against the note). If a lot
+of that title is still open, it receives a note instead of a duplicate. Two entries with the same name (the same
+project told in two neighbouring repositories) share one lot, which declares both repositories in `repos:`. Internal lots (no public title) open nothing;
+a red delivery opens nothing; `cadence deliver --dry-run` announces the articles. The plan is written but **not
+committed** (`deliver` never commits): the line `article à rafraîchir : L9 …` says so. With a plan kept by another
+tool (read-only), the same line carries the instruction to open the lot with that tool. This replaces the manual
+`sync-site-docs` skill.
+
 ### QA review
 
 No gate and no command here: the QA review comes **after** a delivery, and
@@ -423,6 +481,11 @@ cadence session close --all --depth 2   # sub-folder holding a plan (--depth n:
                                    # exit = the worst code of the projects (2 error, 1 open, 0 closed)
 cadence session next "finish L3" "review L4"    # shown by the next session start; replaces the previous notes
 cadence session next --clear       # erase those notes, on purpose
+cadence session context            # `ctx 42 % (84000/200000)`: the context of YOUR session, as the cadence-hud band publishes
+                                   # it: the one named by $CLAUDE_CODE_SESSION_ID (set in Claude Code's Bash); --session <id>
+                                   # overrides it; with no variable, the folder decides only if a single session publishes for it
+                                   # (two sessions in one folder = exit 2, "pass --session"); exit 2 too when no fresh figure
+                                   # (band not loaded) = treat as at the threshold
 ```
 
 `session start` records its time in the worktree's state (`session.json`, under the git dir); the next
@@ -525,13 +588,21 @@ beta · en cours rien · dérive aucune · notes : aucune · prochain T2 Second
 | Column | Content |
 |---|---|
 | `en cours` | ids of the lots in progress; `(aucune activité)` when it has none at all, `(silencieux Nj)` when the lot's last activity (commit, note or start) is more than `--idle` days old (default 3) |
-| `dérive` | the gaps `raf check` reports, counted and the first two shown |
+| `dérive` | the gaps `raf check` reports (a lot whose commits leave a document behind, [`docs.sync`](#documentation-that-follows-the-code), included), counted and the first two shown |
 | `notes` | the notes left by the last `session close`, joined with ` / ` and cut at 120 characters |
 | `prochain` | the first ready lot (quick wins first) — id and title cut at 60 characters |
 | `dépôt` | `non commité` (modified or untracked files), `non poussé` (commits ahead of the upstream), `livraison en cours` (live delivery lock); `propre` otherwise |
 
+When an orchestrated wave is live, one more line closes the tour (not part of `--json`): `vagues en cours : 1 · sessions en cours : 0 · créneaux libres : 1 sur 2` — the lead reads the free slots there instead of computing them (L141).
+
 `--json` prints the same content as an array of objects (`project`, `doing`, `drift`, `notes`,
-`next`, `repo`, and `error` when the project could not be read). The tour is read-only: it changes
+`next`, `repo`, and `error` when the project could not be read), plus `progress` — `{ done, doing, todo, added7 }`,
+the lots done / in progress / to do (dropped and recurring lots left out) and those created in the last 7 days (L149), which
+[`cadence-hud`](plugins/cadence-hud/README.md) draws as one progress bar per project. Projects come in the order of the
+`priority:` key of the folder's `cadence.yaml` (the one `orchestrate --continue` reads), the others after, alphabetically; an unreadable `cadence.yaml` or
+a `priority:` that is not a list of names (`priority: ol`, `priority: []`) keeps the alphabetical order and adds a first row `cadence.yaml · ✗ erreur : <cause>` (`project: "cadence.yaml"` with `error` in `--json`).
+"Created in the last 7 days" means today and the six days before. When the folder has no sub-project but is itself a project, the tour is that project's single line
+(this is what `cadence-hud` asks from a session opened inside a project). The tour is read-only: it changes
 no plan. It exits 0 even when a project is in error — that project's line reads
 `beta · ✗ erreur : <cause>`. The `lead` skill runs it instead of one subagent per project.
 
@@ -634,6 +705,8 @@ cadence deliver              # 0 delivered and verified · 1 a step failed · 2
   reservation number that looks like one) is not a delivered lot. Plan upkeep
   commits (see "Plan upkeep needs no lot") are skipped in that list: they cite
   lots without delivering anything.
+- With [`docs.articles`](#an-article-elsewhere-that-follows-the-delivery), a green delivery of lots with a
+  public title also opens the lot `Article <project> à rafraîchir` in the plan.
 
 ### A project with its own delivery script
 
@@ -751,11 +824,40 @@ cadence orchestrate maritime-atlas:Q4/accueil-4-ux12@haiku   # a lot id may cont
 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 --continue [--until 18:00] [--priority cadence,maritime]   # the wave draws the next ready lot itself (below)
 cadence orchestrate --status [<wave>]        # the live waves and the repositories they hold, then the table (default: the last wave of this folder)
 cadence orchestrate --status [<wave>] --watch [--interval 10]   # the same, redrawn every 10 s (--interval in seconds); stops by itself when no wave is running (with an explicit `<wave>`: when that wave is no longer running)
 cadence orchestrate --resume [<wave>] [--budget 1M] [--answer ol-companion:L22 "reply"]
 ```
 
+**`--continue` — idle time (L147)**: lots given on the command line open the wave (none: the first ones are drawn from the
+plan too); then, each time the lots in play are finished, the wave **draws the next ready lots of the plan** — up to the
+session cap — and plays them in the same wave (same budget, same state folder, journal line `continue : tire …`). A lot
+is drawn when it is `todo`, its `after` is lifted, it is not recurring, neither its title nor a note says « à décider »
+(« à décider avec … », « (à décider) »: a lot waiting for a human decision), it is not already in the wave, and its own budget (derived from its estimate)
+fits in the budget left — otherwise the next one that fits is taken (a lot that does not fit in what is left of the current
+round is not dropped: it is tried again at the next round, once the budget allows it). A round takes at most **one lot per
+repository** while other repositories have ready lots — the pool plays the lots of one repository one after the other, so a
+second one would leave a session idle — and is completed with the same repository when nothing else is ready. Projects are visited in the declared **priority**:
+`--priority cadence,maritime`, or a `priority: [cadence, maritime]` list in the `cadence.yaml` of the folder you launch from
+(the parent of the projects); a name also covers `name-…` (`maritime` → `maritime-atlas`), the other projects come after, in
+alphabetical order. Launched from inside a project, only that project is drawn. A `priority:` key that cannot be read is refused before anything
+starts, lots given or not. A candidate that preflight refuses (dirty tree, Node missing…) is skipped with its cause in the
+journal (`continue : lot sauté — <cause>`; for the first draw also on the error output). Drawing stops — `continue : arrêt — <reason>` — at: the budget, the
+time window (`--until HH:MM`, today's clock: nothing new is drawn from then on, a running lot is not cut), the usage limit,
+a question asked (the wave stays resumable with `--answer`), two lots handed back in a row, an interrupted wave, or no ready
+lot whose estimate fits the budget left. `--resume … --continue` draws again after the resumed lots. `--dry-run --continue` replays the
+draws round by round with the same function as the wave (one lot per repository per round, pre-check, budget counted on the estimates) and
+names the candidates skipped with their cause: `tour 1 : a:L2, b:L2 · tour 2 : a:L3, a:L4`. Drawing happens between rounds: a round of up to `--max-sessions` lots must finish before the next draw.
+
+**Chaining without the human (L148)**: the `lead` skill, once the human has chosen the first lots and the order, does not ask « next? »
+after a lot that comes back ready: it re-verifies it, records `raf done`, pushes, delivers, has the `qa-reviewer` check the
+delivered app, then starts the next wave with `--continue`, in the declared priority — one project at a time, within the two-session
+limit. Before each new wave it reads the context of its own session with `cadence session context` (the figure of the `ctx` segment of the `cadence-hud` band, which publishes the context of each session to `~/.cadence/orchestrate/hud-context/<session id>.json`; the command picks the file named by `$CLAUDE_CODE_SESSION_ID`, set in the environment of the session's Bash, never "the latest file of the folder" — two sessions of one folder alternate; without the band loaded in that session the command exits with code 2, and a missing or stale figure counts as at the threshold); from
+**60 %** upward it starts nothing: it runs `session-close` in each project touched, writes its memory and records three lines for next
+time (`cadence session next`). Stays with the human: the first choice and the order, the questions a session raised, the UX
+reservations; a lot that is not ready, a red delivery or a blocking QA finding is reported and not chained over.
+
 **Lot ids containing `/` (L120)**: the first `:` separates the project from the lot, a final `@` the model, and the lot
 keeps its `/` (`maritime-atlas:Q4/accueil-4-ux12@haiku`); this holds for `--dry-run`, `--status`, `--resume` and
 `--answer` too. In `.cadence/runs/<wave>/` the `/` of the lot becomes `__` (`maritime-atlas--Q4__accueil-4-ux12.json`,
@@ -796,6 +898,22 @@ orchestrate:
 
 `full` is also the model of the UX review and of the single pass of a small lot that is not light.
 
+**Effort level per pass** (L137). Each session is launched with `claude -p --effort <level>` (Claude Code 2.1.284; an
+older `claude` is refused at launch unless every pass is `default`). Defaults: `precheck` low (it only reads),
+`implement` and `fix` medium, `review` high (`review-small` follows `review`), `ux` high. A project overrides any of them
+in `cadence.yaml`; the levels are `low`, `medium`, `high`, `xhigh`, `max`, and `default` sends no `--effort` (the
+level of the session, as before this key). The format-retry session (`--resume`) keeps the level of its pass, and
+`--dry-run` shows the flag in each command line.
+
+```yaml
+orchestrate:
+  effort: { precheck: low, implement: medium, fix: medium, review: high, ux: high }   # defaults
+```
+
+To measure what a level costs, run the same kind of wave before and after changing the key: each step of
+`<wave>/<project>--<lot>.json` records its `effort`, its `tokens` and its `started` / `ended` times (a step from a wave
+older than L137, or with `default`, has no `effort`); compare the totals per `kind` between the two waves.
+
 **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,
@@ -919,7 +1037,7 @@ A slot or a registry entry is owned by a pid **and** its start time: a reused pi
 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
-still holds (those not yet released), the cap of each wave and the slots in use.
+still holds (those not yet released), the cap of each wave, the slots in use and the **free slots** (`créneaux libres : N sur 2`: 2 minus, for each live wave, the smaller of its cap and the repositories it still holds — the figure the `lead` skill reads before starting a subagent). Without an identifier it then prints the table of the wave launched most recently from this folder (by launch time, not by alphabetical order of the identifier).
 
 **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
@@ -932,8 +1050,14 @@ tree (screenshots left at the root, a commit) is an incident of that lot only: t
 
 **Budget**: the wave counts input + cache writes + output tokens (default 2 M); cache reads are kept and
 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
+`--dry-run`): it bounds the *writing* passes, never the reviews. A lot that spent it gets no further implementation or
+fix and is handed back to the lead, but its review (and UX review) is played first; a fix pass starts only if
+the remaining budget can also pay the review that follows it (65 k tokens reserved: a fixed amount close to the 90th
+percentile of the full reviews, 62.7 k over 187 reviews; the short review after the minors pass has a higher p90, 67.6 k
+over 114; measured on 2026-10-09 in the wave journals `.cadence/runs`, `tokens.counted`, 67 waves from 10-04 to 10-09).
+Exception: when the tests are red after a write pass, the lot goes to a fix pass without a review; if that fix pass is
+refused for lack of budget the lot is handed back to the lead without a review, with its findings, and the cause names
+the red tests: the pass it names is the one whose tests were red, counted by its number (« la passe fix 2 », « l'implémentation »), and « la passe des mineurs » appears only when that pass was the one played. 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,
@@ -964,6 +1088,7 @@ orchestrate:
   test: npm test                         # run by the orchestrator after a work step (optional)
   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
+  effort: { review: xhigh }              # effort level per pass (see « Effort level per pass »): precheck, implement, fix, review, ux
   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
@@ -1138,7 +1263,19 @@ after it ended, then disappears. A background command counted for more than an h
 record of when it started, is no longer shown as running: it moves to a grey `N cmd sans fin
 vue` ("end never seen") right after `N cmd`, because its end notification may never have reached
 the session. Waves are read from disk (`~/.cadence/orchestrate/waves/`, then `.cadence/runs/`); no
-cadence command is run, and the CLI is not required.
+cadence command is run, and the CLI is not required for those. One more block needs it: the **progress of the plans**,
+one line per active project (a project with open lots), in the order of `priority:`:
+
+```
+ol      ▮▮▮▮▮▯▯▯▯▯ 39/78 · 0 en cours · +3 cette semaine
+cadence ▮▮▮▮▮▯▯▯▯▯ 10/20 · 2 en cours
+```
+
+The bar is lots done over lots done + in progress + to do (dropped and recurring lots left out);
+`+N cette semaine` counts the lots created in the last 7 days (today and the six before) and is left out at zero. The source is
+`cadence lead tour <folder> --json` (the folder a wave was launched from, otherwise the session's: a folder of projects gives one line per project, a project with no sub-project gives its own single line),
+read again at every wave transition and otherwise every minute; without `cadence` on the PATH, the
+lines are simply not drawn.
 
 Install it as a plugin from the same marketplace:
 
@@ -1149,7 +1286,8 @@ Install it as a plugin from the same marketplace:
 
 `/hud` hides or shows the band. `/hud cmd` lists the background commands being counted (id, tool,
 origin `session` or `agent <id>`, age, name; `(sans fin vue)` on the ones above). Any other argument
-answers `argument inconnu : … (attendu : cmd)` and leaves the band as it is. The source lives in [`plugins/cadence-hud`](plugins/cadence-hud/README.md)
+`/hud projets` folds the project list to one line, and opens it again. Any other argument
+answers `argument inconnu : … (attendu : cmd, projets)` and leaves the band as it is. 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

package/bin/cadence.js

@@ -29,6 +29,7 @@ if (tool === 'raf') {
   cadence session start|close --all [--depth 1]   depuis un dossier non dépôt : une section par projet des sous-dossiers
   cadence session next "ligne" …       notes pour la prochaine session (remplacent les précédentes)
   cadence session next --clear         efface ces notes ; sans ligne ni --clear, la commande refuse
+  cadence session context [--session <id>]   contexte de la session (variable CLAUDE_CODE_SESSION_ID, sinon la seule du dossier) publié par la bande cadence-hud ; code 2 sans chiffre frais
   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
@@ -38,8 +39,10 @@ if (tool === 'raf') {
   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)
+                    --continue [--until HH:MM] [--priority a,b] : tire seul les lots prêts du plan, jusqu'à une borne
   cadence lead tour [dossier] [--idle 3] [--json]
-                    le tableau du lead, sans modèle : une ligne par sous-dossier qui a un plan
+                    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
   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;

package/dist/articles.js

@@ -0,0 +1,86 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { isOpen } from './plan.js';
+/** Titre du lot ouvert à la livraison. */
+export const articleTitle = (name) => `Article ${name} à rafraîchir`;
+const SECTIONS_SHOWN = 12;
+/** Titres d'un article : lignes `#` du Markdown (hors en-tête YAML) et balises `<h1>`…`<h6>` d'une page Astro ou MDX. */
+export function articleHeadings(text) {
+    const body = text.replace(/^/, '').replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, '');
+    const found = [];
+    for (const m of body.matchAll(/^(#{1,6})[ \t]+(.+?)[ \t]*#*[ \t]*$/gm))
+        found.push({ at: m.index, heading: { level: m[1].length, text: m[2].trim() } });
+    for (const m of body.matchAll(/<h([1-6])\b[^>]*>([\s\S]*?)<\/h\1>/gi)) {
+        const t = m[2].replace(/<[^>]+>/g, '').replace(/\s+/g, ' ').trim();
+        if (t)
+            found.push({ at: m.index, heading: { level: Number(m[1]), text: t } });
+    }
+    return found.sort((a, b) => a.at - b.at).map((f) => f.heading);
+}
+const words = (s) => new Set(s
+    .normalize('NFD')
+    .replace(/[̀-ͯ]/g, '')
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((w) => w.length >= 5));
+/**
+ * Sections à relire : celles dont le titre partage un mot (5 lettres au moins, sans accents ni casse) avec un titre public
+ * livré ; sans recoupement, toutes les sections de premier niveau (`##`), faute de mieux.
+ */
+export function articleSections(text, titles) {
+    const headings = articleHeadings(text);
+    const wanted = new Set(titles.flatMap((t) => [...words(t)]));
+    const matching = headings.filter((h) => [...words(h.text)].some((w) => wanted.has(w))).map((h) => h.text);
+    const picked = matching.length ? matching : headings.filter((h) => h.level === 2).map((h) => h.text);
+    return picked.slice(0, SECTIONS_SHOWN);
+}
+/**
+ * Après une livraison verte (L144) : pour chaque article déclaré, ouvre dans ce dépôt le lot « Article <projet> à rafraîchir »
+ * — ou, s'il en est déjà un d'ouvert, y ajoute une note. La note cite les titres publics livrés et les sections à relire ;
+ * le lot déclare le ou les dépôts voisins (`repos`, filtrés par le nom du projet : le dépôt de l'article est partagé entre projets).
+ * Les entrées de même nom partagent un seul lot, qui déclare tous leurs dépôts.
+ * Ne sauve pas le plan. Aucun titre public livré : rien à rafraîchir.
+ */
+export function openArticleLots(o) {
+    const result = { opened: [], noted: [], manual: [], warnings: [] };
+    const titles = [...new Set(o.delivered.map(o.publicTitle).filter((t) => !!t))];
+    if (!titles.length)
+        return result;
+    // Un lot par nom de projet : deux articles de même nom (deux dépôts voisins) se jouent ensemble dans le même lot.
+    const byName = new Map();
+    for (const rule of o.rules) {
+        const name = rule.name ?? o.plan.project;
+        byName.set(name, [...(byName.get(name) ?? []), rule]);
+    }
+    for (const [name, rules] of byName) {
+        const title = articleTitle(name);
+        const repos = [...new Set(rules.map((r) => r.repo))];
+        const articles = rules.map((rule) => {
+            const path = resolve(o.root, rule.repo, rule.file);
+            const sections = existsSync(path) ? articleSections(readFileSync(path, 'utf8'), titles) : null;
+            if (sections === null)
+                result.warnings.push(`article introuvable : ${path}`);
+            return (`Article : ${rule.repo}/${rule.file}. ` +
+                (sections === null ? 'Fichier introuvable à l\'ouverture du lot : vérifier le chemin (docs.articles). ' : `Sections à relire : ${sections.length ? sections.join(' ; ') : '(aucun titre trouvé : relire tout l\'article)'}. `));
+        });
+        const note = `Livraison ${o.sha.slice(0, 7)} : titres publics livrés ${titles.map((t) => `« ${t} »`).join(', ')}. ` +
+            articles.join('') +
+            `Réécrire ce que ces changements rendent faux ou incomplet, sans rien inventer ; les commits ${repos.length > 1 ? 'des dépôts' : 'du dépôt'} ${repos.join(', ')} citent le lot et « ${name} ».`;
+        if (o.plan.readonly) {
+            result.manual.push(`${title} — plan tenu par un autre outil, ouvrir le lot avec lui : ${note}`);
+            continue;
+        }
+        const open = o.plan.lots().find((l) => l.title === title && isOpen(l.status));
+        if (open) {
+            o.plan.note(open.id, note, o.today);
+            result.noted.push(open.id);
+            continue;
+        }
+        const id = o.plan.add(title, o.today, { estimate: 0.5 });
+        o.plan.setRepos(id, repos.map((path) => ({ path, cite: name })));
+        o.plan.note(id, note, o.today);
+        result.opened.push(id);
+    }
+    return result;
+}
+export const describeArticle = (rule) => join(rule.repo, rule.file);

package/dist/audit.js

@@ -4,7 +4,8 @@ import { check } from './check.js';
 import { parse } from 'yaml';
 import { changedFiles, fileAt, readCommits } from './git.js';
 import { linkCommits } from './link.js';
-import { readNewsConfig } from './config.js';
+import { readDocsConfig, readNewsConfig } from './config.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 { isOpen } from './plan.js';
@@ -109,11 +110,24 @@ 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), ...titles, ...gates, ...(plan.hasPublicField ? missingPublicTitles(lots, entries) : []),
+    const issues = [...check(lots, { ...linked, byLot: all.byLot }, today, opts.idle ?? 7), ...newsIssues(lots, entries, newsDir), ...titles, ...gates, ...docSyncIssues(plan, root, all.byLot), ...(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;
 }
+/**
+ * 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.
+ */
+export function docSyncIssues(plan, root, byLot) {
+    const { sync, since } = readDocsConfig(plan.configFile ?? join(root, 'cadence.yaml'));
+    if (!sync.length)
+        return [];
+    return plan
+        .lots()
+        .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) })));
+}
 /** Commits qui portent du travail sur un lot : ni antérieurs à l'adoption du plan, ni réduits au plan. */
 function workCommits(plan, root, commits) {
     const adopted = plan.since;

package/dist/cli.js

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join, relative, resolve } from 'node:path';
 import { parseArgs } from 'node:util';
-import { readHookConfig, readNewsConfig, readPlanConfig, readSessionConfig } from './config.js';
+import { readDocsConfig, readHookConfig, readNewsConfig, readPlanConfig, readSessionConfig } from './config.js';
 import { repoSections, repoShas, resolveLotRepos } from './repos.js';
 import { audit, exemptPlanOnly, ownFiles, isPlanOnly, lotWork, nextUp, planCommits, unreviewedWork } from './audit.js';
 import { short } from './check.js';
@@ -18,8 +18,9 @@ import { dueLine, isRecurring, recurringByDue } from './recurring.js';
 import { schedule } from './schedule.js';
 import { AGENTS_DIR, installAgents, installSkills, SKILLS_DIR } from './skills.js';
 import { findProjects, leadTour, tourLine } from './lead.js';
-import { orchestrate, realOrchestrateDeps } from './orchestrate/command.js';
+import { liveLines, orchestrate, realOrchestrateDeps } from './orchestrate/command.js';
 import { activeLock, REPO_LOCK } from './orchestrate/lock.js';
+import { readHudContext } from './hud-context.js';
 import { sessionClose, sessionStart } from './session.js';
 import { clearNext, readNext, sharedStateDir, stateDir, writeNext } from './state.js';
 const HELP = `raf — plan « reste à faire » versionné dans le dépôt, relié aux commits
@@ -42,8 +43,8 @@ const HELP = `raf — plan « reste à faire » versionné dans le dépôt, reli
   raf ignore <sha> | "<sujet exact>" [--reason texte]   acquitte un commit sans lot (ou citant un id inconnu) sans réécrire l'historique ; raf check --ignored les liste
   raf gantt [-o docs/plan/gantt.html]
   raf hook install      (pre-commit et post-commit ; cadence.yaml hook.autostart: warn|refuse|start)
-  cadence orchestrate <projet>:<lot>[@modèle]… [--budget 2M] [--dry-run] [--wave nom]   une session claude neuve par étape ; --status [vague] [--watch [--interval s]] ; --resume [vague] [--budget 1M] [--answer projet:lot "réponse"]
-  cadence lead tour [dossier] [--idle 3] [--json]   le tableau du lead, sans modèle : une ligne par sous-dossier qui a un plan (en cours, dérive, notes de clôture, prochain lot prêt, dépôt)
+  cadence orchestrate <projet>:<lot>[@modèle]… [--budget 2M] [--dry-run] [--wave nom] [--continue [--until HH:MM] [--priority a,b]]   une session claude neuve par étape ; --status [vague] [--watch [--interval s]] ; --resume [vague] [--budget 1M] [--answer projet:lot "réponse"]
+  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 seul s'il est lui-même un projet (en cours, dérive, notes de clôture, prochain lot prêt, dépôt)
   cadence verify [--retry s] [--sha rév]   rejoue deliver.verify hors livraison : 0 vert, 1 effet rouge, 2 rien à vérifier
   raf news new <lot…> [--title t] | list | check | stamp | build [-o dossier]   (aussi « cadence news … »)
 
@@ -115,6 +116,7 @@ function dispatch(argv, io) {
             status: { type: 'string' },
             since: { type: 'string' },
             idle: { type: 'string' },
+            session: { type: 'string' },
             all: { type: 'boolean' },
             depth: { type: 'string' },
             output: { type: 'string', short: 'o' },
@@ -140,7 +142,7 @@ function dispatch(argv, io) {
     if (!isDay(today))
         throw new RafError(`RAF_TODAY invalide : ${today} (attendu AAAA-MM-JJ)`);
     const root = gitRoot(io.cwd) ?? io.cwd;
-    // Le tour parcourt les sous-dossiers : il ne lit ni le plan ni le cadence.yaml du dossier courant.
+    // Le tour parcourt les sous-dossiers (ou, sans sous-projet, prend le dossier lui-même s'il est un projet) : il ne lit pas le plan du dossier courant.
     if (command === 'lead') {
         if (rest[0] !== 'tour' || rest.length > 2)
             throw new RafError('usage : cadence lead tour [dossier] [--idle 3] [--json]');
@@ -155,9 +157,14 @@ function dispatch(argv, io) {
             io.out(JSON.stringify(rows, null, 2));
         else if (rows.length === 0)
             io.out(`aucun projet sous ${parent} (docs/plan/raf.yaml ou cadence.yaml avec plan:)`);
-        else
+        else {
             for (const r of rows)
                 io.out(tourLine(r));
+            // les créneaux libres viennent du registre, le lead les lit au lieu de les calculer (L141)
+            const [slots] = liveLines();
+            if (slots)
+                io.out(slots);
+        }
         return 0;
     }
     // --all balaie les sous-dossiers : il ne lit ni le plan ni le cadence.yaml du dossier courant.
@@ -401,6 +408,9 @@ function dispatch(argv, io) {
             throw new RafError('usage : raf hook install|pre-commit|post-commit');
         }
         case 'session': {
+            // Le contexte de la session ne dépend d'aucun dépôt : le lead le lit depuis le dossier parent.
+            if (rest[0] === 'context')
+                return sessionContext(io, values.session);
             if (!gitRoot(io.cwd))
                 throw new RafError('session : à lancer dans un dépôt git');
             // « next » n'écrit que les notes : la commande du projet ne se joue qu'à la reprise et à la clôture.
@@ -426,7 +436,10 @@ function dispatch(argv, io) {
                 throw new RafError(`pas de configuration de livraison : ${configPath} (voir « cadence.yaml » dans le README)`);
             const config = parseDeliverConfig(readFileSync(configPath, 'utf8'), configPath);
             const plan = existsSync(planPath) ? loadPlan() : null;
-            const ctx = { root, state: sharedStateDir(root), plan, config, today, dryRun: !!values['dry-run'], sha: values.sha, args: rest, out: io.out, err: io.err };
+            const articles = readDocsConfig(configPath).articles;
+            // Sans public: d'un lot visible, le site reprend le titre de sa Nouveauté la plus récente.
+            const publicTitle = (lot) => lot.public ?? (lot.visible ? loadEntries(newsDir).find((e) => e.lots.includes(lot.id))?.title : undefined);
+            const ctx = { root, state: sharedStateDir(root), plan, config, today, dryRun: !!values['dry-run'], sha: values.sha, args: rest, articles, publicTitle, out: io.out, err: io.err };
             return deliver(ctx, realDeps(root));
         }
         case 'verify': {
@@ -764,6 +777,14 @@ async function sessionAll(rest, values, io) {
     }
     return worst;
 }
+/** Le contexte de la session de `--session <id>`, sinon de `CLAUDE_CODE_SESSION_ID`, sinon (variable absente) de la seule session du dossier courant, tel que la bande cadence-hud le publie ; illisible = code 2, à lire comme « au seuil ». */
+function sessionContext(io, session) {
+    const r = readHudContext(io.env, io.now().getTime(), { cwd: io.cwd, session });
+    if (!r.ok)
+        throw new RafError(`session context : contexte illisible — ${r.reason} ; à traiter comme au seuil`);
+    io.out(`ctx ${Math.round(r.ctx.percent)} % (${r.ctx.tokens}/${r.ctx.window})`);
+    return 0;
+}
 function session([sub, ...args], ctx, values) {
     switch (sub) {
         case 'start': {
@@ -798,6 +819,6 @@ function session([sub, ...args], ctx, values) {
             return 0;
         }
         default:
-            throw new RafError('usage : cadence session start [--since …] [--idle 2] | close [--since …] | start|close --all [--depth n] | next "ligne" … | next --clear');
+            throw new RafError('usage : cadence session start [--since …] [--idle 2] | close [--since …] | start|close --all [--depth n] | next "ligne" … | next --clear | context [--session id]');
     }
 }