@sylad/cadence 1.6.0 → 1.7.0

package/docs/overview.md

@@ -0,0 +1,27 @@
+[← cadence](../README.md)
+
+# Overview: the tools and the skills
+
+The longer introduction the README used to open with.
+
+A small working method that lives in your repository. Solo developers and
+AI-assisted sessions lose track of *what is left to do* and *what each commit
+was for*; cadence keeps both in plain files next to the code.
+
+Four tools:
+
+- **raf** (French *reste à faire*, "what is left to do"): the plan, linked to your commits;
+- **news**: a user-facing changelog with screenshots, tied to the plan;
+- **session**: the facts to start and to close a work session;
+- **deliver**: wait for the CI of the pushed commit, deploy, then **verify the effect**.
+
+And four [Claude Code](https://claude.com/claude-code) skills that turn them
+into rituals — `session-start`, `session-close`, `deliver`, and `lead` to pilot
+several projects through subagents — plus three reviewer agents: `ux-reviewer`
+(no user-facing change is done before its usability review) and `code-reviewer`
+(no lot with commits is done before its code review), each behind an opt-in
+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.md): a status band above the Claude
+Code prompt that shows the session's context, quota, cost and the orchestrate waves running.

package/docs/raf.md

@@ -0,0 +1,192 @@
+[← cadence](../README.md)
+
+# raf
+
+- The plan is a YAML file in the repo (`docs/plan/raf.yaml`), edited by the CLI.
+  Your comments and hand edits are preserved.
+- A commit belongs to a lot when its message cites the id: `feat(L3): …`,
+  `fix: L3/t1 …`. The link is **computed from `git log`**, never stored, so
+  committing never dirties the plan. The id is read as a whole word: `XL3`,
+  `L3x` and `L3.4` do not cite `L3`, while `L3.` at the end of a sentence does.
+  When the subject has a scope that cites lots (`feat(L3): …`,
+  `chore(L31,L32): …`), **the scope alone decides**: a passing mention
+  (`page équipe (L27)`), a range (`L28–L31`, `L45 à L48`) or the body does not
+  count. Without a scope citing a lot, the whole message is read as before.
+- `raf check` audits drift between the plan and the history.
+- Plan upkeep needs no lot. A commit is plan upkeep when **every file it
+  touches is a plan file**: the plan itself, its Gantt page (only at its default place, `gantt.html` next to the plan — written elsewhere with `raf gantt -o`, declare it under `plan.files`), the `plan:` key of the config file in use (`cadence.yaml`, or
+  the `--config` file; a change to `deliver:`/`session:` is work), or a file the
+  project lists under `plan.files` in `cadence.yaml` (a page it generates from
+  the plan, a journal), or the QA expectations file (`docs/qa/expectations.md`,
+  or the file named by `qa.expectations`; the lead commits the `qa-reviewer`'s draft of it). Such a commit is never a "commit without a lot", and it
+  does not count as work on the lots it cites: it is absent from `raf commits`,
+  does not start a `todo` lot, does not make a code review stale, and
+  `cadence deliver` does not announce the lots it cites as delivered. The files
+  decide, never the subject: a `chore(plan): …` commit that touches a source
+  file is a commit like any other.
+- `raf gantt` writes a single self-contained HTML page (no server, no CDN).
+
+```sh
+npm install -g @sylad/cadence    # or: npx -p @sylad/cadence raf …
+
+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
+raf add "write the migration" --parent L1     # → L1/t1
+raf start L1
+git commit -m "feat(L1): dedup by calendar month"
+raf now                           # in progress, next up (quickwins first), recently done
+raf done L1/t1 && raf done L1
+raf check                         # exit 1 on drift
+raf gantt                         # docs/plan/gantt.html
+```
+
+## Commands
+
+| Command | Effect |
+|---|---|
+| `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 [--screen page\|component\|journey]] [--spec] [--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:`; `--screen`: the screen a visible lot creates or changes — a new `page`, a new `component` or a modified `journey` — written as `screen:` right after `visible:`, shown by `raf show`; it requires `--visible`, and `raf check` reports a `screen:` without `visible:` or with another value as an error. Only `page` triggers the spec step of `orchestrate` (L209), never inferred from the title; `--spec`: the lot changes a behaviour (something a user, an API client or another service can observe), written as `spec: true` right after `screen:`, `visible:`, `quickwin:` or `estimate:` (whichever comes last), shown by `raf show`, refused on a sub-task. Also set by the lead at planning time, never inferred from the 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 screen <id> page\|component\|journey\|none` | set, replace or remove `screen:` on an existing lot, to adopt the [spec step](orchestrate.md#the-spec-step-of-a-lot-with-screen) on a plan already written (only `page` adopts the [spec step](orchestrate.md#the-spec-step-of-a-lot-with-screen); `component` and `journey` do not); refused on a lot without `visible:` (like `raf add --screen`) and on a sub-task; `none` removes the key and leaves `visible:` alone |
+| `raf spec <id> on\|off` | set or remove `spec:` on an existing lot (a lot that changes a behaviour, for the back-end spec step of `cadence orchestrate`, see [The spec step of a lot with `spec: true`](orchestrate.md#the-spec-step-of-a-lot-with-spec-true)); refused on a sub-task; `off` is refused on a lot that has `screen: page` (the page implies the spec: remove `screen:` first) and `on` there only says so and changes nothing; on `component` and `journey` (ordinary path since L209) both work and set or remove the back-end `spec:`. `raf spec` only takes `on`/`off`: `cadence spec check\|qa <fiche.yaml>` keeps its own subcommands. `raf check` reports a `spec:` that is neither `true` nor `false` (`spec : true ou false attendu`) |
+| `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 todo <id> [--reason text]` | put a started lot back to `todo` (`doing` → `todo`, `started:` removed, dated note « remis en attente : reason »): refused when work commits cite the lot (plan-only and version commits do not count, as `raf commits`), when the lot is not `doing` (a `done` or `dropped` lot is reopened by hand), or on a sub-task; sub-tasks and other keys are left as they are |
+| `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`, neighbouring repositories included); `--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; a lot that declares `repos:` ([neighbouring repositories](orchestrate.md#a-lot-whose-work-is-in-a-neighbouring-repository)) gets, after them, one `dépôt <path> :` section per neighbour with the commits there that cite the lot and fall within the lot's period (`started` to `finished`) and, when the lot declares a `cite:` for that neighbour, contain that string (`aucun commit du lot`, or `introuvable` for a path that is not there) |
+| `raf now` | what to do next |
+| `raf list [--status s]` | flat list |
+| `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, or only version fields, `CHANGELOG.md`, the README's « What's new » section and `docs/whats-new.md` 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 post-commit hook (read-only, never blocks) and the pre-commit hook (does nothing unless `hook.autostart` says so, see below) |
+
+### A commit on a lot that is still `todo`
+
+By default the post-commit hook only warns (`L1 est encore todo — raf start L1`). The `hook.autostart`
+key of `cadence.yaml` changes what the **pre-commit** hook does when the message cites a `todo` lot
+(a recurring lot, a lot already `doing`, a commit without a lot and a plan-upkeep commit are never concerned):
+
+```yaml
+hook:
+  autostart: refuse   # warn (default) | refuse | start
+```
+
+- `warn`: today's behaviour, the commit goes through, the post-commit hook warns.
+- `refuse`: the commit fails, loudly, with `raf start <id>` in the message (`--no-verify` still bypasses it).
+- `start`: the hook runs `raf start <id>` and stages the plan, so the plan change is **in the same commit** —
+  no amend afterwards, no dirty plan left behind. Only when `docs/plan/raf.yaml` is identical to `HEAD` (no
+  uncommitted change to the plan, staged or not): otherwise nothing is started, the hook says why
+  (`plan modifié non commité : démarrage automatique sauté, raf start <id> à la main`) and behaves like `warn`.
+
+The pre-commit hook reads the message from the command line of the `git commit` that runs it (`-m`, `-am`,
+`--message`, `-F`; Linux, through `/proc`) or from `CADENCE_COMMIT_MESSAGE`. When the message is not known yet
+(editor, `--amend`) it does nothing and the post-commit warning stays. Run `raf hook install` again to add the
+pre-commit block to an existing repository. A read-only plan is never started by the hook. Only a refusal (exit code 3 of `raf hook pre-commit`) stops a commit: an older or broken `raf` lets it through.
+
+Global options: `--file path` or `RAF_FILE`; `RAF_TODAY=YYYY-MM-DD` to freeze
+the date. `cadence raf …` is the same as `raf …`.
+
+## Plan file
+
+```yaml
+version: 1
+project: my-app
+prefix: L
+since: 2026-09-28     # commits before this date are not audited
+ignore: ['^chore\(batch\):']   # optional: subjects of automated commits, neither audited nor counted for a lot
+lots:
+  - id: L1
+    title: Monthly dedup on merge
+    status: doing        # todo | doing | done | dropped
+    estimate: 2          # working days
+    quickwin: false
+    visible: true        # user-facing: a news entry is expected when done
+    after: [L0]
+    gate: { count: 8, spec: true }   # optional: not before 8 lots with `spec: true` are done (or `screen: page`)
+    created: 2026-09-28
+    started: 2026-09-29
+    notes:
+      - { date: 2026-09-29, text: "keep the bank line when both sources exist" }
+    tasks:
+      - { id: t1, title: write the migration, status: done }
+```
+
+## A plan elsewhere, or in another format
+
+`cadence.yaml`, at the repository root, can say where the plan is. The short form keeps raf's own
+format, and the plan stays writable:
+
+```yaml
+plan: planning/todo.yaml
+```
+
+A project that publishes its plan (a JSON generated from it and committed with it)
+declares that file, so a commit touching only the plan and its published copy is
+plan upkeep; the plan keeps raf's format and stays writable:
+
+```yaml
+plan:
+  files: [frontend/public/plan-data/plan.json]
+```
+
+Until the file is declared, such a commit is reported as a "commit without a
+lot" when it cites none, and counts as work on the lots it cites.
+
+A project that already keeps its plan with its own tool is read **without migrating it**: describe
+the file, and `raf now`, `raf list`, `raf commits`, `raf check`, `raf gantt` and
+`cadence session start|close` work on it. Such a plan is **read-only** —
+`raf add|start|done|note|ux|review` refuse and leave the file to the project's tool, and the two
+review gates do not apply to it (a `uxSince` or `reviewSince` written in it is ignored).
+
+```yaml
+plan:
+  path: docs/plan/taches.yaml
+  project: my-app               # what the file does not say itself: project, since, ignore
+  since: 2026-10-02
+  ignore: ['^plan: ']
+  files: [docs/plan/journal.ndjson]   # kept with the plan: a commit touching only these is a plan commit
+  lots: taches                  # root key holding the list (default: lots)
+  fields:                       # raf field: key in the file (a list = first one present)
+    title: titre
+    public: titre_public        # the lot's title for the public; read when it is text, else ignored
+    screen: ecran               # page, component or journey; only on a visible lot (only `page` enters the spec step)
+    spec: fiche                 # true or false: the lot changes a behaviour
+    status: etat
+    estimate: effort
+    created: cree_le
+    started: demarre_le
+    finished: [livre_le, ferme_le]
+    notes: note
+    repos: depots               # the lot's neighbouring repositories (a list of paths and/or { path, cite }, or one of them)
+    parent: parent
+  statuses:                     # raf status: their states
+    todo: [prevu, specifie]
+    doing: [en_cours, teste]
+    done: [deploye, valide]
+    dropped: caduc
+  estimates: { S: 0.5, M: 1, L: 3 }   # their effort labels, in working days
+```
+
+- Fields: `id`, `title`, `status`, `estimate`, `quickwin`, `visible`, `screen`, `spec`, `public`, `every`, `last`, `after`, `created`, `started`,
+  `finished`, `notes`, `repos`, `parent`, `gate`; one left out is read under its own name. A timestamp counts for
+  its day; a note written as plain text is one note.
+- `gate` (L219) is a drawing condition added to `after`: `gate: { count: N, spec: true }` or `gate: { count: N, screen: page }` (N an integer ≥ 1, one criterion). It is written by hand in the plan (no `raf add` option). The count is the number of `done` lots of the same plan that carry the criterion (`todo`, `doing`, `dropped` lots and sub-tasks do not count; recurring lots do). Until the count reaches N, a `todo` lot is *waiting*, never *ready*: `raf now` lists it on a line `en attente de condition de tirage : L190 (2/8 lots spec: true faits)` (the existing `en attente de dépendances : …` line stays for lots waiting on `after`), `cadence session start` adds an `En attente` section (nothing when no lot is gated) and leaves the lot out of `À suivre` and of the proposals, `cadence lead tour` skips it for `prochain` and adds `attend L190` to the project's line (and `waiting` to `--json`, only when a lot waits), `cadence orchestrate` refuses it before any action (`a:L190 : condition de tirage non remplie : 2/8 lots spec: true faits`) and `--continue` never draws it, and `raf show` prints `gate : 8 lots spec: true faits`. Once the count is reached the lot is ready like any other (the field stays in the plan); a lot already `doing` is not refused for its condition. A malformed `gate` is reported by `raf check` (`gate invalide : …`) and the lot is never drawable. A plan without `gate` behaves exactly as before; `after` read by the Gantt scheduling is unchanged.
+- `spec` is the exception to « a left-out field is read under its own name »: a read-only plan's `spec:` is often the path of a spec document, so it is read only when `plan.fields.spec` maps it, and then only `true` counts (any other value is neither an error nor a spec step). Natively, `spec:` stays `true` or `false` (L198). Consequence for a `gate: { count: N, spec: true }` in a read-only plan: it counts only lots whose `spec` is mapped by `plan.fields.spec`; without that mapping the count stays 0 and the lot waits for good, with no `raf check` problem. `gate: { count: N, screen: page }` has no such condition.
+- `parent`: an entry `B33/t1-fusion` whose parent is `B33` becomes the sub-task `t1-fusion` of `B33`.
+- Ids need no prefix: a commit belongs to a lot when its message cites one of the plan's ids as a
+  whole word (`E-A2`, `NC2.4`, `B33/t1-fusion`).
+  An id that is not in the plan cannot be told from ordinary text: such a commit counts as
+  "without a lot", never as an unknown reference.
+- A state missing from `statuses`, or an effort label missing from `estimates`, is reported by
+  `raf check`.
+
+## Gantt scheduling
+
+One lane of work. Finished lots use their real dates (or their commits' dates);
+lots in progress run until `max(start + estimate, today)`; lots to do follow in
+file order, after their dependencies, on working days.

package/docs/releasing.md

@@ -0,0 +1,59 @@
+[← cadence](../README.md)
+
+# 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`, and write the version's section of
+   `CHANGELOG.md` (`## [x.y.z] - date`, what changes for the user, lots cited), in **one commit that holds
+   only those files** (the version fields and the CHANGELOG, nothing else in the manifests, the « What's new »
+   section of the README, the one place of it a release rewrites, and `docs/whats-new.md`, its long form: add the version there too). Such a commit is
+   exempt from the code-review gate like a plan commit: it closes the lot after its review, and `raf check`
+   does not ask for a new one (nor does it count it as a commit without a lot). The « What's new »
+   summary is ordered by version, a number known only at the release and shared by several lots: write it
+   in that commit, not before the review. A commit that touches any other file
+   — or another field of a manifest, or a dependency in `package-lock.json` — is work like any other and has
+   to be reviewed.
+2. Run the plugin evaluation, `npm run eval:plugin` (billed, see [Evaluating the plugin](#evaluating-the-plugin-before-a-release)),
+   on that version commit; a case below the threshold stops the release until you have read it in the report.
+3. `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` 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`).
+4. Watch the run: `gh run watch` (or `gh run list --workflow publish.yml`).
+5. 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`.
+
+`.github/workflows/tests.yml` runs the type-check and the test suite on the same runner image, Node 24 and `npm ci` as the publish job, and never publishes: start it with `gh workflow run tests.yml --ref <branch>` or by pushing a `diag/**` branch, to see on the runner what a red publish run saw.
+
+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
+publish run, leaves npm behind without any other error — 0.3.0 and 0.4.0 were never published — hence
+step 5.
+
+## Evaluating the plugin (before a release)
+
+`evals/` holds an evaluation suite for the plugin itself, run by `claude plugin eval` (Claude Code 2.1.263 and later). Each case is
+a folder with a `prompt.md` and `graders/*.md`, and replays a trap found by hand: `raf-done-sans-revue` (`raf done` refused on a lot whose
+commits have no code review, with no `--force` to get round it), `deliver-sha` (`git push origin <sha>:main` then
+`cadence deliver --sha <sha>` for a pushed commit that is not `HEAD`), `orchestrate-id-avec-slash` (`maritime-atlas:Q4/accueil-4-ux12@haiku`
+keeps its `/`) and `livrer-sh-sans-bloc` (a `./livrer.sh` without a `deliver:` block in `cadence.yaml` is not
+run by `cadence deliver`). Every case also runs a **baseline without the plugin**, so the report gives the score of each arm and the
+difference: a trap the baseline already avoids proves nothing about the plugin. The cases are read-only questions (tools `Read`, `Glob`, `Grep`,
+`Skill`, no scaffold script), each graded by a regular expression and by a model-judged criterion.
+
+```sh
+npm run eval:plugin              # claude plugin eval . --max-cost-usd 5 --no-publish; 4 cases × 3 runs × 2 arms = 24 runs
+claude plugin eval . --case deliver-sha --runs 1 --trust-plugin --no-publish --max-cost-usd 1    # one case, one run (the first run asks to trust the plugin)
+```
+
+**Every run is billed** (a full `claude` session on your own credential, plus the judge): the suite is run at the release, once the
+version commit is ready, never in `npm test`, in `prepublishOnly` or in CI, and `--max-cost-usd 5` aborts a runaway. A case below
+the threshold (1.0 by default, `--threshold`) makes the command exit 1: read the case in the report before deciding it is the plugin
+and not the wording of the case. `npm test` only checks that the
+files are well formed (`test/plugin-evals.test.ts`); `evals/` is not part of the npm package.

package/docs/session.md

@@ -0,0 +1,107 @@
+[← cadence](../README.md)
+
+# session
+
+```sh
+cadence session start              # notes from the last close, lots in progress (silent ones flagged),
+                                   # work done since yesterday by lot, drift, repo state, 3 proposals
+cadence session start --since "3 days ago" --idle 2
+cadence session close              # commits by lot since the last `session start`,
+                                   # commits without a lot, lots in progress with no commit in that window,
+                                   # drift, uncommitted / unpushed work; exit 1 while something is still open
+cadence session close --since "2 days ago"   # --since overrides the window
+cadence session start --all        # from a folder that is not a repository: one "## project" section per
+cadence session close --all --depth 2   # sub-folder holding a plan (--depth n: n levels down, 1 by default);
+                                   # 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
+`session close` takes it as its window and names it in the section title: `Commits de la période (depuis
+l'ouverture de 09:12)` (with the date when it is not today). A close never moves the boundary, refused
+or not: run again without a `session start` in between (the `session-close` skill does, after fixing a
+point), it still reports since that opening instead of an empty period. With no recorded opening, or an
+unreadable file, the window is the current day, said as such (`depuis 2026-09-28 00:00`); `--since` is
+quoted as given. (A `session.json` written by 0.18.0 after a close, `depuis la clôture de …`, is still read.)
+
+On success `cadence session next` prints what it recorded (`2 lignes enregistrées pour la prochaine
+ouverture`, then the lines as written, blank ones dropped), so `session-close` can report
+them without running `session start` again.
+
+`--all` runs the same command inside each project found under the current folder —
+`docs/plan/raf.yaml`, or a `cadence.yaml` with `plan:` — and never enters a project
+to look for another. `--since` and `--idle` go to every project; an error in one
+project is printed in its section and the others still run. It replaces the shell
+loop over the sub-folders. A project that is not the root of its own git repository gets a `✗` line
+(and exit 2) instead of the parent repository's plan. `--all` and `--depth` are refused outside `session` (`--depth` is also read by `cadence lead tour`),
+and `--all` refuses `--file`, `--config` and `RAF_FILE`: each project reads its own plan. For a one-line-per-project overview, `cadence lead tour`.
+
+`cadence session next` without a line refuses (exit 2) and leaves the notes of the
+last close as they are — it used to erase them silently; erasing is `--clear`.
+
+Proposals come from the plan only: lots in progress, then ready lots (dependencies
+done), quick wins first. Local state lives in the git directory, never committed:
+the close notes per worktree, the delivery lock and log in `.git/cadence/`, shared
+by all the worktrees of a clone.
+
+A project that already has its own morning and evening scripts keeps them: name
+them in `cadence.yaml` and their output is added to the report, under "Faits
+propres au projet", before the proposals (start) or the verdict (close).
+
+```yaml
+session:
+  start: ./scripts/morning.sh "$CADENCE_SINCE"    # sh, at the repo root, 120 s at most
+  close: ./scripts/evening.sh "$CADENCE_SINCE"
+```
+
+```yaml
+session:
+  clean: [ "~/projects/tmp/*", "tmp/*", "test-output-*" ]   # working files to propose for removal at close
+  cleanDays: 7                                              # older than this many days (default 7)
+```
+
+`cadence session close` then lists, under "Nettoyage proposé", the entries matching these
+patterns (`*` stands for part of a name and never crosses a `/`; `~` is the home folder, a
+relative pattern starts at the repo root) that were not modified for more than `cleanDays`
+days, oldest first — a folder's age is that of the most recent entry it contains, at any depth,
+and an entry's age runs from the later of its modification time and its status-change time (ctime):
+what `tar xf`, `cp -a` or `rsync -a` just brought in with an old modification time is not old.
+
+An entry is proposed only if it could be measured entirely. Never proposed:
+
+- a git repository, a folder that contains one at any depth, and anything under a `.git` folder;
+- a git directory without a `.git` entry — a bare repository (`git init --bare`, `git clone
+  --mirror`, `backup.git/`), a `--separate-git-dir`, a worktree's admin folder —, recognised by
+  its content as git does (`HEAD` with `objects` and `refs`, or `HEAD` with `commondir`): neither
+  it, nor anything inside it, nor a folder that contains one;
+- anything `git` tracks, in any repository that has a `.git` entry above it. One limit, stated
+  plainly: a bare repository driven with an external work tree (`git --git-dir=~/.dotfiles
+  --work-tree=~`) leaves no `.git` beside the files, so its tracked files cannot be recognised and
+  can be proposed — never point a pattern at such a work tree;
+- a name starting with `.` unless the pattern itself starts that name with `.` (as in the
+  shell, `tmp/*` does not match `tmp/.env`; `tmp/.cache-*` does);
+- anything reached through a symbolic link matched by a `*` segment: unlike the shell, the walk
+  never descends into such a link (`tmp/*/*` lists nothing behind `tmp/link → ../outside`), and a
+  folder's age never looks behind a link; the link itself can be proposed, as a link — removing it
+  leaves its target alone. Only segments written in full *before* the first `*` follow a link, as
+  `cd` would (`~/shared/*` with `~/shared` a link lists the target's entries); once a `*` has been
+  crossed no link is followed any more, even on a segment written in full (`tmp/*/out/*` with
+  `tmp/run1/out → /elsewhere` lists nothing behind `out`);
+- anything that could not be read entirely: a folder that cannot be listed — nor anything
+  inside it, even named in full —, an entry that cannot be examined or vanished during the
+  walk, an entry under a `.git` that `git` could not answer for. These are listed apart,
+  under "Nettoyage : N élément(s) illisible(s), jamais proposé(s)";
+- the repository itself, or a folder that contains it.
+
+The command deletes nothing, never fails on the cleanup and does not change the exit code: the
+`session-close` skill shows the list and removes the entries only after the human agrees.
+
+The commands get `CADENCE_SINCE` and `CADENCE_TODAY`. `CADENCE_SINCE` is the `--since` as given; on `session close` without `--since` it is the instant of the last `session start` as an ISO 8601 UTC string (`2026-09-28T07:12:00.000Z`), or `<today> 00:00` when no mark exists.
+The commands add facts and decide nothing: a failing command is reported and changes neither
+the exit code nor the verdict.

package/docs/skills.md

@@ -0,0 +1,76 @@
+[← cadence](../README.md)
+
+# Claude Code skills
+
+As a plugin:
+
+```
+/plugin marketplace add Sylad/cadence
+/plugin install cadence@cadence
+```
+
+gives `/cadence:session-start`, `/cadence:session-close`, `/cadence:deliver`,
+`/cadence:lead` and the `ux-reviewer`, `code-reviewer` and `qa-reviewer` agents. Or copy them into the
+repository with `cadence skills install` (to `.claude/skills/cadence-*` and
+`.claude/agents/cadence-*.md`; `--dir` for another `.claude` folder,
+`--force` to overwrite local edits).
+
+- **session-start**: reports the facts briefly, proposes three lots from the
+  plan, then waits for your priority — nothing starts before your answer.
+- **session-close**: plan hygiene, clean repository, a cleanup proposal for stale
+  working files (`session.clean` patterns, older than `session.cleanDays`; never
+  anything git tracks, a git repository or a folder holding one, anything under
+  `.git`, a bare repository or separate git directory or anything inside one,
+  anything behind a symbolic link a `*` matched (only the link itself), a hidden `.xxx` name a `*` would not match, nor anything it could not
+  read entirely — it asks before deleting), memory limited to what the
+  repository does not say, new skills or agents proposed but never created, three
+  lines for next time.
+- A project with its own tooling keeps it: its plan is read where it is (`plan:`),
+  its delivery script is called by `cadence deliver` (`deliver.script`), its
+  morning and evening scripts feed the session report (`session:`), and its own
+  skills can become one-line aliases of `session-start` / `session-close`.
+- **deliver**: dry run, delivery, and on failure the cause fixed rather than a
+  blind retry; after a green delivery that changes what a page shows or what it
+  is served, the `qa-reviewer` agent walks the delivered app.
+- **lead**: from a folder holding several projects, `cadence lead tour` (a program,
+  no model: see [lead tour](lead.md#lead-tour)) prints one line of facts per project, you choose the priorities, the lots are delegated with
+  `cadence orchestrate` (fresh short sessions with a standard brief — test first,
+  README and usage documentation updated with the change, commits citing the lot, no push — reviewed by the `code-reviewer` agent, see
+  [orchestrate](orchestrate.md#orchestrate); a lot with `screen: page` first goes through the [spec, mockup review and accept steps](orchestrate.md#the-spec-step-of-a-lot-with-screen)), 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
+  blocking findings come back to you. As many
+  subagents as the session cap at most (2 by default, `CADENCE_MAX_SESSIONS`), never two in the same repository. The whole flow is drawn in
+  [docs/lead.md](lead.md); how a lot, a wave, the lead and the service of cadence itself fit together, in four figures, is in
+  [docs/fonctionnement.md](fonctionnement.md).
+- **ux-reviewer** (agent): captures at 1440 and 390 px, findings grounded in a
+  named rule (Nielsen, WCAG 2.2 AA) or a measurement, ranked, turned into
+  `raf add --parent` sub-tasks, and a one-line verdict for `raf ux`. It never
+  edits code. Read-only for real: its `tools:` list is `Read, Grep, Glob, Bash` and the
+  Playwright tools (`mcp__playwright`, and `mcp__plugin_playwright_playwright` when the
+  browser comes from the Playwright plugin) — no `Edit`, no `Write`. Outside a wave it gives its captures a relative file name only, which the Playwright MCP writes under `.playwright-mcp/` (the same rule as the wave's briefs); `qa-reviewer` follows it too.
+- **code-reviewer** (agent): any stack; given a repository and a lot id, it reads
+  the diff itself from the commits that cite the lot — not the author's summary —
+  and the project's CLAUDE.md, when there is one, for its conventions; findings grounded in a
+  measurement (a failing command, changed code without a test, a duplicated
+  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. A README or usage
+  documentation that does not follow the lot's change is a *major* finding.
+- **qa-reviewer** (agent): any web app (read-only like `ux-reviewer`: same tool list, no `Edit`, no `Write`); given a repository and a base URL (and
+  optionally a lot id, to walk only the pages it touched — those that call the
+  changed endpoints, those of the screens it changed, the pages that consume the services the lot changed,
+  and the home page; a backend-only lot stays in scope, and when the lot changes no route
+  and no screen, or the endpoints cannot be mapped to pages, every page is walked; the others are named « Not walked »), it opens each page of
+  the project's expectations file in a real browser at 1440 and 390 px and
+  measures: expected content present and non-empty, no error or missing-data
+  message, every API call answered 2xx with a non-empty body, no console error,
+  no broken content image. It reads the page as text first and takes a capture only for a gap. Findings are defects (a line of the expectations
+  broken, or a universal check failing with a visible effect, with or without an
+  expectations file), suspects (it looks like missing or wrong data and no
+  expectation settles it) or noise (a console error or a failed request with no
+  visible effect, ranked minor) or already planned (an open lot covers it: returned in one line, the lot id and its title), ranked, each with
+  the route, what was expected, what was measured and the evidence; pages checked
+  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.

package/docs/spec.md

@@ -0,0 +1,60 @@
+[← cadence](../README.md)
+
+# spec
+
+`cadence spec check <fiche.yaml>` checks a **sheet** (`fiche.yaml`, the machine-readable output of the spec step): a **screen sheet** (a lot with `screen:`), a **back-end sheet** (a lot that changes a behaviour without a screen) or a **mixed sheet** with both parts. The screen part is designed in
+[docs/superpowers/specs/2026-10-10-etape-spec-design.md](superpowers/specs/2026-10-10-etape-spec-design.md)). Start from the template
+[`templates/fiche.yaml`](../templates/fiche.yaml) (it passes the check as is), a worked example sits next to the design. It prints one
+`✗ …` line per violation and exits **0** when the sheet is valid, **1** with violations, **2** when the file is missing, is not YAML or the usage is wrong. The invariants:
+
+- `ecran` has `id`, `titre`, `route` (starts with `/`), `lot`, `maquette`, and `largeurs: [1440, 390]`; `etats` holds at least `vide`, `chargement`, `erreur`, none twice;
+- `champs[]`: a unique kebab-case `id` (it is also the mockup's `data-testid`), `libelle`, `type`, `source`, and a boolean `obligatoire`;
+- `regles[]` are numbered `R1`, `R2`… in order with no gap; each has an `etat` that is one of `etats`, an `enonce`, a `message` (the exact text on screen, or `null`),
+  a `statut` — `sourcee` with the `source` it comes from, or `hypothese` with the `si_faux` that says what would change — and at least one planned test, named `Rn — …`;
+- `masque` (optional, only on a rule of state `vide`) lists the fields the rule makes disappear: every id must be a field of the sheet and none may be one the rule shows in `champs`;
+- `actions[]` are numbered `A1`… in order, their `declencheur` is a field id (or `null` for the page load), their `appel` reads `VERB /path`, and the `regles` they carry exist.
+
+**Back-end sheet** (L187; design: [docs/superpowers/specs/2026-10-11-etape-spec-back-design.md](superpowers/specs/2026-10-11-etape-spec-back-design.md)). Start from [`templates/fiche-back.yaml`](../templates/fiche-back.yaml) (it passes the check as is); a worked example, a real lot of ol-companion, sits next to the design. The sheet has `sujet` instead of `ecran` (no `etats`, `champs`, mockup), and the same `regles`. The back-end invariants, one `✗ …` line each:
+
+- `sujet` has `id` (kebab-case, the folder name `docs/specs/<id>/`), `titre`, `lot`, and a `perimetre` with `modules`, `endpoints` and `jobs` (lists of texts, at least one entry in the three) and an optional `hors_perimetre`;
+- `cas[]` are numbered `C1`, `C2`… with no gap, each with `titre`, `acteur`, `declencheur`, `preconditions`, `nominal` (a non-empty list of steps), `resultat`, and `alternatives` — a list of `{ si, alors, regles }`, each citing at least one existing rule — or `alternatives: []` with its reason in `sans_alternative`; every case is cited by at least one rule;
+- a back-end rule has `cas` (at least one existing case id) instead of `etat`, plus the screen rule's `enonce`, `statut` (`sourcee` + `source`, or `hypothese` + `si_faux`) and tests named `Rn — …`; `message`, `champs` and `masque` only make sense on a rule attached to a state;
+- `contrats[]` are numbered `A1`… with no gap, each with an `appel` (`VERB /path`, `job <name>` or `commande <name>`), `entree`, `sortie`, `erreurs` — a list of `{ code, message }` where `code` is `HTTP <n>` or `log debug|log|warn|warning|error|info|critical|fatal|verbose` and `message` the exact text — or `erreurs: []` with its reason in `sans_erreur`, and the `regles` it carries exist;
+- `donnees[]` are numbered `D1`…, each with `objet`, `note`, a boolean `existant` and a `modification` (`aucune`, `ajout` or `changement`); an existing object that is modified carries the `decision` of the lead (the answer to the targeted question). The list may be empty (`[]`: the lot touches no data).
+
+**Mixed sheet** (a lot with `screen:` and a back-end part): `sujet` **and** `ecran` side by side, with the same `id` (the folder name) and the same `lot`. A rule is attached to a state (`etat`, a screen rule) or to cases (`cas`), at least one of the two. The `A` ids are shared: the actions of the screen and the `contrats` are numbered `A1…An` with no gap over the whole, and an action that calls an API already listed in `contrats` points to it with `contrat: Ax` instead of repeating its `appel`. An action that has its own `appel` equal to the `appel` of a contract is reported (it must point to the contract). A sheet without `ecran` refuses `actions`, `etats` and `champs` (they only make sense with a screen part), and a rule with `etat` there gets that single report. A sheet that only has `ecran` stays valid as it is (no migration); `sujet` is required as soon as the lot is back-end or mixed.
+
+`cadence spec check` prints the same summary line for each kind (`N cas, N règles (N hypothèses), N contrats, N données` for a back-end sheet) and keeps its exit codes: 0 valid, 1 violations, 2 usage.
+
+`cadence spec reseal <lot> <test> --reason texte` is the lead's way to correct one sealed acceptance test of the lot in progress that contradicts its sheet (unchanged, or amended by commits of the lot, L217; of a delivered lot, also by commits of another delivered lot, L229) (of a delivered lot: add `--porteur <lot in progress>`), see [The accept step](orchestrate.md#the-accept-step-red-acceptance-tests-and-their-lock).
+
+`cadence spec qa <fiche.yaml>` derives from a valid sheet the section of `docs/qa/expectations.md` for its screen and prints it on the standard output
+(it never writes the file: you paste the section, and the lead commits it like the rest of the plan files). A sheet with violations prints them on the
+error output, nothing on the standard one, and exits 1. The derivation is built so that the planned empty and error states are never reported as defects:
+
+- `## <route>` is the screen's route;
+- `shows:` — one line per mandatory field (its `libelle`), **except** the fields that belong to a state (listed in `champs` of a rule of state `vide` or `erreur`, like the empty-state message);
+  the line of a field listed in the `masque` of a `sourcee` rule of state `vide` ends with `— unless <the rule's statement>`; the other fields (a static title) never get one;
+- `never:` — the messages of the rules of state `erreur`, on one line; the message of a rule of state `vide` is a planned display and never goes there;
+- `api:` — the load actions only (`declencheur: null`) in `GET` (the QA pass never sends a POST); the line ends with `may be empty when <the rule's statement>` when a `sourcee` rule of state `vide` carries the action.
+  Actions triggered by a field stay with the acceptance tests.
+
+`spec qa` only derives the **screen** part: a back-end sheet, which has no `ecran`, is refused (exit 2, « la fiche n'a pas de partie écran »); on a mixed sheet it reads the actions' calls through their `contrat`.
+
+
+
+## Spec step (design, first steps delivered)
+
+For a visible lot that adds a page (`screen: page`; a component or a journey follows the ordinary path since L209), `orchestrate` gets a step
+before the code: a static HTML mockup in the project's own style (1440 and 390 px; empty, loading and
+error states) and a machine-readable screen sheet (fields, numbered rules `R1…` each marked *sourced*
+or *hypothesis*, actions → API calls). The `ux-reviewer` agent reads the mockup before any code; the
+acceptance tests are written from the sheet, red, by a session other than the implementer's; the
+implementation gets the sheet, the code review checks rule → test → green, the hypotheses go into the
+lot's news entry, and a human is asked only about a choice that is costly to undo. The design is in
+`docs/superpowers/specs/2026-10-10-etape-spec-design.md` (with an example sheet and the plan of the
+lots that deliver it). Delivered so far: the sheet templates `templates/fiche.yaml` (screen) and `templates/fiche-back.yaml` (a lot without a screen: `sujet`, `cas`, `regles`, `contrats`, `donnees`), `cadence spec check`
+(the sheet's invariants) and `cadence spec qa` (the screen's `docs/qa/expectations.md` section, derived
+from the sheet), see [spec](#spec) below, and the `spec` step of `orchestrate` itself (the `spec-writer` agent, the
+render at 1440 and 390 px, the commit of the spec), see [The spec step](orchestrate.md#the-spec-step-of-a-lot-with-screen) in `orchestrate`; the `accept` step (red acceptance tests and the lock that protects them), see [The accept step](orchestrate.md#the-accept-step-red-acceptance-tests-and-their-lock); the UX review of
+the mockup (the `ux-reviewer` agent in mockup mode), see [The mockup review](orchestrate.md#the-mockup-review-before-any-code); and the downstream briefs (the sheet given to `implement`, rule → test → green in the code review, a light UX conformity pass, the `## Hypothèses` section of the news entry), see [The downstream briefs](orchestrate.md#the-downstream-briefs-sheet-rule--test--green-conformity-hypothèses).

package/docs/stabilite.md

@@ -0,0 +1,35 @@
+[← cadence](../README.md)
+
+# Stability
+
+From 1.0.0 cadence follows [semantic versioning](https://semver.org): what is listed under
+*Guaranteed* only changes incompatibly in a major version; a minor or a patch never breaks it.
+
+**Guaranteed**
+
+- **Commands and options** of `raf` and `cadence` (`cadence raf …` is `raf …`): `init`, `add`, `start`, `done`, `drop`,
+  `note`, `did`, `public`, `screen`, `spec`, `ux`, `review`, `commits`, `show`, `list`, `now`, `ignore`, `check`, `gantt`, `hook`;
+  `cadence news`, `session` (`start`, `close`, `next`, `context`), `lead tour`, `corrections`, `deliver`, `verify`, `orchestrate`,
+  `skills`, `spec` (`cadence spec <lot> on|off` is `raf spec`; `check`, `qa`: exit **0** when the sheet is valid and the section is printed, **1** with violations, **2** on a missing or unreadable file or a wrong usage);
+  their options and exit codes as the pages [raf](raf.md), [orchestrate](orchestrate.md), [deliver](deliver.md), [spec](spec.md), [news](news.md), [session](session.md), [lead](lead.md), [corrections](corrections.md) and [skills](skills.md) document them. A new command or option is a minor change.
+- **The keys of `cadence.yaml`**: `plan`, `news`, `hook`, `session`, `deliver`, `orchestrate`, `docs`, `qa`, `priority`, `depth`, `lead` (`lead.ux`)
+  and the keys each of them takes. A key is not renamed nor removed, nor does its meaning change; a new key is a minor change.
+- **The plan file** (`docs/plan/raf.yaml`): `project`, `prefix`, `since`, `ignore`, `lots` (with their
+  fields, `tasks`, `notes`, `repos`) and `acknowledged`, and the plan formats `plan:` in `cadence.yaml` can read.
+  The `version` key is kept in the file but ignored (`src/plan.ts` does not read it): it is not a schema version.
+- **The names of the skills** (`session-start`, `session-close`, `deliver`, `lead`) **and of the agents**
+  (`ux-reviewer`, `code-reviewer`, `qa-reviewer`).
+
+**Not guaranteed** (may change in any release)
+
+- The **text of the outputs**: wording, layout, order of the lines and columns of every report, table and message
+  (the `--json` outputs and the exit codes are part of the commands above). In a `--json` output a new field is a
+  minor change, so consumers must tolerate unknown fields; removing or renaming a field is a major change.
+- The **`precheck-reader`**, **`spec-writer`** and **`acceptance-writer`** agents, and the mockup and conformity modes of **`ux-reviewer`**: internal to `cadence orchestrate`, not meant to be called by hand.
+- The **`cadence-hud` band**: its segments, colours and layout; it is versioned on its own.
+- The **wave journals** under `.cadence/runs` and the files `cadence orchestrate` keeps there.
+- The wording of the briefs and of the instructions inside the skills and the agents.
+- The **format of the sheets** (`fiche.yaml`: the screen sheet `templates/fiche.yaml`, the back-end sheet `templates/fiche-back.yaml`, the mixed sheet) and so the invariants `cadence spec check` enforces: experimental while the next bricks of the spec step (S3–S6) still reshape it, a sheet that passes today may be refused by a later release. The `spec` commands and their exit codes are guaranteed, the keys they read are not yet.
+
+There is no schema version and no migration: a file written by an earlier release keeps working, and a key a
+release adds is optional.