@sylad/cadence 0.5.0 → 0.7.0

package/.claude-plugin/marketplace.json

@@ -6,7 +6,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.5.0",
+      "version": "0.7.0",
       "source": "./",
       "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 two reviewer agents (UX, code).",
-  "version": "0.5.0",
+  "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.7.0",
   "author": { "name": "Sylvain Ladoire" },
   "homepage": "https://github.com/Sylad/cadence",
   "repository": "https://github.com/Sylad/cadence",

package/README.md

@@ -13,9 +13,11 @@ Four tools:
 
 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 two reviewer agents, each behind an
-opt-in gate: `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).
+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.
 
 ## raf
 
@@ -23,8 +25,17 @@ review) and `code-reviewer` (no lot with commits is done before its code review)
   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.
+  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.
 - `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, or a file the
+  project lists under `plan.files` in `cadence.yaml` (a page it generates from
+  the plan, a journal). 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 and does not make a code review stale. 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
@@ -54,7 +65,7 @@ raf gantt                         # docs/plan/gantt.html
 | `raf commits <id>` | the commits counted for a lot (the set the code review gate uses), one `<sha> <subject>` per line, oldest first |
 | `raf now` | what to do next |
 | `raf list [--status s]` | flat list |
-| `raf check [--since date] [--idle 7]` | since the plan's adoption date by default: commits without a lot (commits touching only the plan are exempt), unknown ids, `todo` lots that already have commits, idle lots, `done` lots with open sub-tasks, bad or circular dependencies |
+| `raf check [--since date] [--idle 7]` | since the plan's adoption date by default: commits without a lot (commits touching only plan files are exempt), unknown ids, `todo` lots that already have commits, idle lots, `done` lots with open sub-tasks, bad or circular dependencies |
 | `raf gantt [-o file]` | standalone Gantt page |
 | `raf hook install` | add the (non-blocking, read-only) post-commit hook |
 
@@ -94,6 +105,18 @@ format, and the plan stays writable:
 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** —
@@ -175,6 +198,15 @@ captures: [captures/l8.png]
 Imported statements now read **3.000** as three thousand, not three.
 ```
 
+A screenshot can say what it shows: write it as `{ file, alt }` instead of a
+bare path, one text per screenshot.
+
+```yaml
+captures:
+  - { file: captures/l8-before.png, alt: "Statement total read as 3 instead of 3,000" }
+  - captures/l8-after.png          # a bare path still works: no alternative text
+```
+
 | Command | Effect |
 |---|---|
 | `cadence news new <lot…> [--title t]` | entry skeleton, dated and timed now (`date`, `created`), titled after the lot |
@@ -187,7 +219,11 @@ Imported statements now read **3.000** as three thousand, not three.
 The Markdown is deliberately small: paragraphs, `-` lists, `**bold**`,
 `` `code` ``, `[links](url)`; everything else is escaped text. The JSON holds
 `{ project, generated, entries: [{ slug, title, date, lots, captures, html }] }`,
-with screenshot paths relative to the JSON file.
+with screenshot paths relative to the JSON file. `captures` is always a list of
+paths; an entry that gives at least one alternative text also carries `alts`,
+the texts in the same order (`""` for a screenshot without one) — an entry
+without any keeps exactly the shape above. The built page puts the text in the
+image's `alt`, and falls back to "Capture : <title>".
 
 **Order.** Everywhere (`list`, `build`, the JSON), entries are strictly newest
 first: by `date`, then, on the same day, by creation time. Every entry carries
@@ -214,8 +250,8 @@ raf ux L8 "no screen: calculation fix"
 
 With the rule on, `raf done` refuses a visible lot without a review (`--force`
 to override) and `raf check` reports visible lots finished after the `uxSince`
-day without one. An empty verdict is refused. Plans without `uxSince` are not
-affected.
+day without one. An empty verdict is refused, and one left empty or blank by hand
+in the YAML counts as no review. Plans without `uxSince` are not affected.
 
 ### Code review
 
@@ -229,8 +265,8 @@ The counterpart of the UX review, off by default. With the rule on, `raf done`
 refuses a lot that has at least one commit citing it and no recorded verdict
 (`--force` to override), and `raf check` reports such lots finished after the
 `reviewSince` day. A lot with no commit has nothing to review; neither does a
-lot whose only commits touch the plan itself, predate the plan's `since` or
-match an `ignore:` pattern — `raf commits <id>` prints exactly the counted set.
+lot whose only commits touch plan files alone (the plan, or a file listed under
+`plan.files`), predate the plan's `since` or match an `ignore:` pattern — `raf commits <id>` prints exactly the counted set.
 
 The verdict is tied to what was reviewed: `raf review` stores it on the lot with
 the sha of the lot's latest counted commit (`review: { date, verdict, commit }`,
@@ -239,7 +275,75 @@ makes the review stale: `raf done` refuses (`--force` to override), and
 `raf check` reports a finished lot, until the lot is reviewed again and
 `raf review` is rerun. A verdict
 written by hand without a `commit` field is not checked for staleness. An empty
-verdict is refused. Plans without `reviewSince` are not affected.
+verdict is refused, and one left empty or blank by hand in the YAML counts as no
+review. Plans without `reviewSince` are not affected.
+
+### QA review
+
+No gate and no command here: the QA review comes **after** a delivery, and
+`raf done` does not wait for it. It follows any delivery that changes what a
+page shows or what it is served (screen, API, data source, configuration of
+either) — in practice every delivery except docs-, plan- or tests-only ones: a
+backend-only lot can empty a page without touching a screen, and the agent then
+starts with the pages that call the changed endpoints. The `qa-reviewer` agent
+opens each page of the running app in a real browser and judges it from the
+user's side. A page can be empty while everything else is green — no code
+changed, a data source went down upstream, the unit tests replace the network,
+`/api/health` answers ok, and the "nothing found" on screen is the message the
+code was written to show.
+
+The agent cannot tell such an empty state from a normal one by itself: the
+project says what each page must show, in `docs/qa/expectations.md` — one
+`## <route>` section per page, three kinds of lines:
+
+```markdown
+# QA expectations
+
+## *
+- shows: the header and the navigation links
+- never: "Loading failed", "Too Many Requests"
+- api: /api/live/current — may be empty when no match is within 24 hours
+
+## /players
+- shows: the squad of the last match — at least 11 players
+- shows: the season statistics table, 8 columns — 1440 only
+- never: "No recent line-up found"
+- api: /api/squad/last — a non-empty list
+
+## /fixtures/:id   (the first match linked from /fixtures)
+- shows: both team names, the date, the score once the match is played
+- never: "Unknown match"
+- api: /api/fixtures/:id
+```
+
+- `shows:` — content that must be present and non-empty, with a count where one exists;
+- `never:` — texts that must not appear: error messages, and empty-state messages that mean
+  missing data;
+- `api:` — the calls the page depends on: each must answer 2xx with a non-empty body (a 200 with
+  `[]`, `{}` or `null` is a failure, unless its line says `may be empty when …`).
+
+An optional `## *` section holds what every page must show, never show and call. A line may end
+with a condition in plain words, which the agent honours: `may be empty when …`, `1440 only`,
+`390 only` (a line without a width holds at both). Content hidden on the phone by design is not a
+defect unless a `shows:` line requires it at 390; content pushed outside the visible area (it
+needs a sideways scroll) is reported as suspect and handed to `ux-reviewer` in one line.
+
+The rest is free text, written for a reader: a line can be repeated, and a route with a parameter
+names a real value to visit or says where to find one. The file can live elsewhere:
+
+```yaml
+# cadence.yaml
+qa:
+  expectations: docs/quality/pages.md
+```
+
+Only the agent reads that key; the CLI does not use it. Without an expectations file the agent walks
+the routes it discovers and still runs its universal checks: an error shown, a failed API call
+whose content is missing on screen, a broken or missing content image are defects with or without a
+file; an empty 2xx body, like whatever else would need an expectation to judge, is suspect at most
+(it may be a normal absence). For a route with a
+parameter, it finds a real value in the app's links or its API responses and says how it built the
+URL. The agent then returns a draft for you to correct — it never writes the file itself.
 
 ## session
 
@@ -250,9 +354,13 @@ cadence session start --since "3 days ago" --idle 2
 cadence session close              # today's commits by lot, commits without a lot, lots in progress
                                    # with no commit today, drift, uncommitted / unpushed work
                                    # exit 1 while something is still open
-cadence session next "finish L3" "review L4"    # shown by the next session start
+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 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
@@ -311,7 +419,10 @@ cadence deliver              # 0 delivered and verified · 1 a step failed · 2
 - Commands get `CADENCE_SHA`, `CADENCE_SHORT` (7 characters) and `CADENCE_BRANCH`;
   `${SHA}` and `${SHORT}` are replaced in `url` and `contains`.
 - On success the lots cited by the commits since the previous delivery are
-  listed, so you can `raf done` those whose effect you have seen.
+  listed, so you can `raf done` those whose effect you have seen. With a
+  read-only plan, only the lots that were in progress when the delivery started
+  are listed: an id quoted in a message for context (a finished lot, a
+  reservation number that looks like one) is not a delivered lot.
 
 ### A project with its own delivery script
 
@@ -354,7 +465,7 @@ As a plugin:
 ```
 
 gives `/cadence:session-start`, `/cadence:session-close`, `/cadence:deliver`,
-`/cadence:lead` and the `ux-reviewer` and `code-reviewer` agents. Or copy them into the
+`/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).
@@ -369,12 +480,16 @@ repository with `cadence skills install` (to `.claude/skills/cadence-*` and
   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.
+  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, one subagent per project
   gathers the facts, you choose the priorities, each lot is delegated to a
   subagent with a standard brief (test first, commits citing the lot, no push),
   reviewed by the `code-reviewer` agent, re-verified by the lead, then delivered
-  one project at a time. Two subagents at most, never two in the same repository.
+  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. Two
+  subagents at most, never two in the same repository.
 - **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
@@ -387,6 +502,20 @@ repository with `cadence skills install` (to `.claude/skills/cadence-*` and
   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.
+- **qa-reviewer** (agent): any web app; given a repository and a base URL (and
+  optionally a lot id, to start with the pages it touched — for a backend-only
+  lot, those that call the changed endpoints), it opens each page of
+  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. 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), 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.
 
 ## Releasing
 

package/agents/qa-reviewer.md

@@ -0,0 +1,122 @@
+---
+name: qa-reviewer
+description: QA reviewer for any web app — after a delivery, walks the pages of the running app in a real browser, from the user's side, and reports empty states, wrong data, error messages, failed or empty API calls, console errors and broken images. Given a repository path and a base URL, it checks each page against the project's expectations file (`docs/qa/expectations.md` — per route, what the user must find, what must never appear, the API calls the page depends on) at a desktop and a phone width; every finding names what it measured (selector or text, count, status code, response size), never an impression; without an expectations file it still runs its universal checks, reports what it saw and returns a draft one. Use after any delivery that changes what a page shows or what it is served (screen, API, data source, configuration of either) — in practice every delivery except docs-, plan- or tests-only ones — or to re-check a deployed app. Read-only — does not modify code, log in or submit anything.
+---
+
+You check a running web app the way its user meets it: page by page, in a real browser. You
+report; you never edit code, the plan or the expectations.
+
+A page can be empty while everything else is green: no code changed, a data source went down
+upstream, the unit tests replace the network, the health endpoint answers ok, and the message on
+screen is exactly the one the code was written to show. Neither a test nor a code review calls
+that a defect. You do: a players page with no players is a defect, whatever the cause.
+
+## Inputs
+
+The absolute path of the repository and the base URL of the app — deployed, or a local server the
+caller started. Optionally a lot id: then start with the pages that lot touched (its title and
+notes in the plan, and `raf commits <id>`, tell which) — when the lot touched only the backend,
+the pages that call the changed endpoints — and walk the others after. If the path or the URL is
+missing, or the URL does not answer, say so and stop.
+
+## Method
+
+1. **Read how to reach the app**: the project's CLAUDE.md, then its README — the routes, the demo
+   data, what sits behind a PIN or a login.
+2. **Read the expectations**: `docs/qa/expectations.md`, or the file named by `qa.expectations` in
+   `cadence.yaml`. One `## <route>` section per page: what the page `shows:` (the content that
+   must be present and non-empty, with a count where one exists), what must `never:` appear (error
+   texts, empty-state messages that mean missing data), and the `api:` calls it depends on (each
+   must answer 2xx with a non-empty body). An optional `## *` section holds what every page must
+   show, never show and call. A line may end with a condition in plain words, which you honour:
+   `may be empty when …`, `1440 only`, `390 only` (a line without a width holds at both). A route
+   with a parameter names a real value to visit, or says where to find one.
+3. **No expectations file: do not guess silently.** Discover the routes (router file, sitemap,
+   navigation links); for a route with a parameter, find a real value in the app's links or its API
+   responses and say how you built the URL. Walk them as in step 4 and report what you saw: the
+   universal checks hold without a file, and anything that would need an expectation to judge is
+   *suspect* at most. Return a DRAFT expectations file as text, for the human to correct: you do not
+   write it into the repository. Say plainly that without expectations an empty state cannot be told
+   from a normal one.
+4. **Open each page in a real browser** (Playwright, or the browser tool available), at **1440 px**
+   and **390 px** wide. Let it settle: after `load`, wait a fixed few seconds, scroll through the
+   page (lazy images), wait again — never for network idle, which streams and polling never reach.
+   Then measure:
+   - the expected content is present and non-empty — name the selector or the text found and its
+     count (`.player-card` ×14), not "the list looks fine";
+   - no `never:` text on screen, and no other error or missing-data message;
+   - every API call of the page — those listed, and those you saw it make to its own backend —
+     answered 2xx with a non-empty body: note the status and the response size (decoded body bytes;
+     streams — SSE, websockets — are exempt from the size rule). A 200 with an empty or null body
+     (`[]`, `{}`, `null`, 0 bytes) is a failure, unless its line says `may be empty when …`. This
+     takes a tool that listens to responses (e.g. a Playwright `page.on('response')` listener): if
+     yours cannot give status and size, say so under "not verified" instead of pretending;
+   - no console error: quote the first line of each;
+   - no broken image among the content images (a failed request, or `naturalWidth` 0): count the
+     items that should carry an image and have no loaded `<img>` — a fallback badge replacing a
+     failed image has no `<img>` at all;
+   - at 390 px, content hidden on the phone by design is not a defect unless a `shows:` line
+     requires it at 390; content pushed outside the visible area (it needs a sideways scroll) is
+     reported as suspect and handed to `ux-reviewer` in one line;
+   - states behind controls: tabs, filters and other controls that only change the view may be used
+     and are part of the page (a tab that triggers its own API call is checked like a page); a
+     control that writes is never used;
+   - pacing: pause between pages; when a 429 (or any rate-limit answer) appears, re-run that page
+     ALONE after a quiet minute before concluding — if it reproduces, an ordinary visitor gets it;
+     if not, it was your own pace and it is not a finding;
+   - the frontend source may be read to LOCATE a cause after a measurement, never as evidence.
+5. **GET only, and nothing that writes**: never log in, never submit a form that writes, never
+   click a control that changes data, never send a POST, PUT, PATCH or DELETE yourself. If a PIN
+   or a login wall is met, say so and stop there for those pages: they go under "not verified",
+   they are neither a finding nor a page checked.
+6. **Classify** what you see:
+   - *defect* — a line of the expectations is broken, or a universal check fails with a visible
+     effect on the page: an error message shown, a failed API call whose content is missing on
+     screen, a broken or missing content image. Universal checks need no expectations file: such
+     a failure is a defect even without one. An API call that answers 2xx with an empty body is a
+     defect only when an expectation says data is due there; without one it is suspect at most
+     (it may be a normal absence);
+   - *suspect* — something that looks like missing or wrong data and that no expectation
+     settles: an empty list under a heading, a "nothing found" message, a status or label
+     contradicted by the page's own data ("eliminated" beside a won match), a stale season
+     label. Say why, and propose the line of expectations that would settle it;
+   - *noise* — a console error or a failed request with no visible effect: reported, ranked minor;
+   - *out of scope* — usability and accessibility belong to `ux-reviewer`, code quality to
+     `code-reviewer`: one line at most, never a finding.
+7. **Rank** each finding: *blocking* (a page's main content is missing, its main information is
+   false, or an error is shown to the user), *major* (secondary content missing or wrong, a section
+   silently dropped after a failed or empty API call, a broken content image), *minor* (noise).
+
+## Output
+
+A short report:
+
+- **Pages checked N/N**, with the base URL and the date and time of the run, and the two widths. The
+  second N is every page of the expectations (or every route discovered): a page you could not open
+  is counted and named, never dropped. A page counts as checked when both widths were measured; a
+  page checked partially (one width, tabs not opened) is counted and named as partial.
+- **Findings**, most severe first, each with: the route, its kind and rank, what was expected —
+  quote the line of the expectations, or name the universal check, or, for a suspect, give the
+  expectation line you propose —, what was measured, and the evidence — status code, response
+  size, the text on screen, the capture. No finding without a measurement.
+- **Not verified**: pages behind a PIN or a login, states that need data you could not get, a
+  browser tool that was missing or could not give status and size — stated plainly.
+- **Proposed follow-ups**: one `raf add "…"` line per finding worth doing; on a read-only plan
+  (`cadence.yaml` maps the fields of a file kept by another tool), plain lines for the project's
+  own tool instead. Without an expectations file, the draft comes here.
+- **Verdict**, one line, alone — e.g. "6/6 pages as expected", "not as expected: 1 blocking
+  (/players shows no player)", "no expectations file: 13 pages walked, 1 defect, 8 suspects, draft
+  returned". It is the last line of the report.
+
+Captures and temporary files go in a temporary directory outside the repository, or in the one
+the caller names; remove them, or list their paths in the report. The working tree is left as you
+found it.
+
+## Do not
+
+- Report an impression: a finding you have not measured in the browser is not a finding.
+- Take a green health endpoint, a passing test suite, or "the code shows this message on purpose"
+  as proof that a page is fine.
+- Excuse an empty page by its cause: an upstream outage explains a defect, it does not remove it.
+- Edit code, the plan or the expectations file, commit, or mark anything done: the session that
+  called you does it.

package/bin/cadence.js

@@ -26,7 +26,8 @@ if (tool === 'raf') {
   cadence session start [--since "24 hours ago"] [--idle 2]
                     faits de reprise : notes de la veille, en cours, fait depuis, écarts, propositions
   cadence session close [--since …]    faits de clôture ; code 1 tant que ce n'est pas fermé
-  cadence session next "ligne" …       notes pour la prochaine session (sans argument : efface)
+  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 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

package/dist/audit.js

@@ -14,15 +14,18 @@ export function planCommits(plan, root, opts = {}) {
     const commits = readCommits(root, opts);
     return patterns.length ? commits.filter((c) => !patterns.some((re) => re.test(c.subject))) : commits;
 }
-/** Le commit ne touche-t-il que le plan (ou la page Gantt) ? */
+/** Commit d'entretien du plan : ne touche-t-il que des fichiers du plan (plan, page Gantt, plan.files) ? */
 export function isPlanOnly(sha, plan, root) {
     const own = ownFiles(plan, root);
     const files = changedFiles(root, sha);
     return files.length > 0 && files.every((f) => own.has(f));
 }
 /**
- * N'ont pas besoin de citer un lot : un commit qui ne touche que le plan (ou la page Gantt), et un
- * commit automatique dont le sujet correspond à un motif `ignore:` du plan.
+ * N'ont pas besoin de citer un lot : un commit d'entretien du plan — TOUS ses fichiers sont des fichiers
+ * du plan (le plan, sa page Gantt, ceux que le projet déclare sous plan.files, son plan publié par
+ * exemple) — et un commit automatique dont le sujet correspond à un motif `ignore:` du plan.
+ * Les fichiers décident, jamais le sujet : « chore(plan): … » qui touche un fichier source est un
+ * commit comme un autre.
  */
 export function exemptPlanOnly(linked, plan, root) {
     const own = ownFiles(plan, root);

package/dist/cli.js

@@ -15,7 +15,7 @@ import { Plan, RafError, STATUSES } from './plan.js';
 import { schedule } from './schedule.js';
 import { AGENTS_DIR, installAgents, installSkills, SKILLS_DIR } from './skills.js';
 import { sessionClose, sessionStart } from './session.js';
-import { sharedStateDir, stateDir, writeNext } from './state.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
 
   raf init [--project nom] [--prefix L] [--no-hook]
@@ -35,6 +35,8 @@ const HELP = `raf — plan « reste à faire » versionné dans le dépôt, reli
   raf news new <lot…> [--title t] | list | check | stamp | build [-o dossier]   (aussi « cadence news … »)
 
 Un commit appartient à un lot quand son message cite l'identifiant : « feat(L3): … », « L3/t1 ».
+Un commit qui ne touche que le plan (et les fichiers déclarés sous plan.files dans cadence.yaml, un plan
+publié par exemple) n'a pas à en citer, et ne compte pas pour les lots qu'il cite ; le sujet n'y change rien.
 Un lot --visible attend une entrée Nouveautés (docs/nouveautes/, --dir) avec capture ; raf check le vérifie.
 Un texte qui commence par « - » se passe après « -- » : raf note L1 -- "-5 %".
 Le plan est docs/plan/raf.yaml, ou celui que nomme « plan: » dans cadence.yaml ; un plan tenu par un
@@ -85,6 +87,7 @@ function dispatch(argv, io) {
             config: { type: 'string' },
             'dry-run': { type: 'boolean' },
             sha: { type: 'string' },
+            clear: { type: 'boolean' },
             help: { type: 'boolean', short: 'h' },
         },
     });
@@ -429,10 +432,26 @@ function session([sub, ...args], ctx, values) {
         }
         case 'close':
             return sessionClose(ctx, { since: values.since ?? `${ctx.today} 00:00` });
-        case 'next':
-            writeNext(ctx.state, ctx.today, args);
+        case 'next': {
+            const lines = args.filter((l) => l.trim() !== '');
+            if (values.clear) {
+                if (lines.length)
+                    throw new RafError('session next --clear efface les notes : ne pas lui passer de ligne');
+                const gone = clearNext(ctx.state);
+                ctx.out(gone ? `notes effacées (${gone.lines.length} ligne(s) du ${gone.date})` : 'aucune note à effacer');
+                return 0;
+            }
+            // Lancée sans ligne (variable vide dans un script, agent pressé), la commande effaçait en silence
+            // les notes de la dernière clôture : effacer se demande exprès.
+            if (lines.length === 0) {
+                const kept = readNext(ctx.state);
+                throw new RafError(`session next : aucune ligne — ${kept ? `${kept.lines.length} ligne(s) du ${kept.date} conservée(s)` : "rien n'est écrit"} ; ` +
+                    'usage : cadence session next "ligne" … (pour effacer les notes exprès : cadence session next --clear)');
+            }
+            writeNext(ctx.state, ctx.today, lines);
             return 0;
+        }
         default:
-            throw new RafError('usage : cadence session start [--since …] [--idle 2] | close [--since …] | next "ligne" …');
+            throw new RafError('usage : cadence session start [--since …] [--idle 2] | close [--since …] | next "ligne" … | next --clear');
     }
 }

package/dist/deliver.js

@@ -343,14 +343,22 @@ async function verifyAll(ctx, deps, sha, env) {
     }
     return null;
 }
-/** Ligne des lots cités depuis la livraison précédente, ou null (première livraison, rien de cité). */
+/**
+ * Ligne des lots cités depuis la livraison précédente, ou null (première livraison, rien de cité).
+ *
+ * Plan en lecture seule : seuls les lots EN COURS sont annoncés. Ses identifiants sont de forme libre, et
+ * un message cite volontiers un numéro qui en a la forme (réserve « R1 » d'une revue) ou un lot clos
+ * nommé pour le contexte — les annoncer « livrés » ferait fermer à tort. L'état est celui du départ de
+ * la livraison : le plan a été lu avant que le script du projet ne ferme lui-même les lots qu'il livre.
+ */
 function deliveredLots(ctx, prev, sha) {
     if (!ctx.plan || !prev || prev === sha)
         return null;
     if (!isAncestor(ctx.root, prev, sha)) {
         return `livraison précédente (${prev.slice(0, 7)}) hors de l'historique de ${sha.slice(0, 7)} (réécrit ?) : lots livrés non calculés`;
     }
-    const known = new Set(ctx.plan.lots().map((l) => l.id));
+    const lots = ctx.plan.lots();
+    const known = new Set((ctx.plan.readonly ? lots.filter((l) => l.status === 'doing') : lots).map((l) => l.id));
     const ids = new Set();
     for (const c of readCommits(ctx.root, { range: `${prev}..${sha}` })) {
         for (const r of ctx.plan.refs(`${c.subject}\n${c.body}`))

package/dist/news.js

@@ -16,8 +16,52 @@ function validStamp(s) {
     return (!Number.isNaN(Date.parse(s.replace(' ', 'T'))) && day.getUTCMonth() === mo - 1 && day.getUTCDate() === d && h < 24 && mi < 60 && sec < 60);
 }
 const list = (v) => (v == null ? [] : Array.isArray(v) ? v.map(String) : [String(v)]);
+const CAPTURE_KEYS = ['file', 'alt'];
+const CAPTURE_SHAPE = '{ file: chemin, alt: "texte alternatif" }';
+/**
+ * Captures de l'en-tête : un chemin, ou `{ file, alt }` quand l'entrée dit ce que l'image montre.
+ * Les chemins restent une liste de chaînes (ce que lit déjà le JSON publié), les textes les suivent un à un.
+ */
+function readCaptures(raw, problems) {
+    const captures = [];
+    const alts = [];
+    for (const [i, item] of (raw == null ? [] : Array.isArray(raw) ? raw : [raw]).entries()) {
+        let file;
+        let alt = '';
+        if (typeof item === 'string' || typeof item === 'number') {
+            file = String(item);
+        }
+        else if (item && typeof item === 'object' && !Array.isArray(item)) {
+            const map = item;
+            if (map.file == null || String(map.file).trim() === '') {
+                problems.push(`capture n° ${i + 1} : fichier absent — ${CAPTURE_SHAPE}`);
+                continue;
+            }
+            file = String(map.file);
+            // Une ligne : le texte part tel quel dans un attribut alt.
+            alt = map.alt == null ? '' : String(map.alt).replace(/\s+/g, ' ').trim();
+            for (const k of Object.keys(map)) {
+                if (!CAPTURE_KEYS.includes(k))
+                    problems.push(`capture ${file} : clé inconnue « ${k} » (attendu : ${CAPTURE_KEYS.join(', ')})`);
+            }
+        }
+        else {
+            problems.push(`capture n° ${i + 1} illisible : un chemin ou ${CAPTURE_SHAPE}`);
+            continue;
+        }
+        // Copiées telles quelles sous le dossier de build : un chemin qui sort du dossier écrirait ailleurs.
+        if (isAbsolute(file) || file.split(/[\\/]/).includes('..'))
+            problems.push(`capture hors du dossier des Nouveautés : ${file}`);
+        // Noms sages : utilisables tels quels dans une URL, et seulement des images.
+        else if (!CAPTURE.test(file))
+            problems.push(`capture ${file} : image .png, .jpg, .webp ou .gif, nom en lettres, chiffres, « . _ - / »`);
+        captures.push(file);
+        alts.push(alt);
+    }
+    return { captures, alts };
+}
 export function parseEntry(file, text) {
-    const entry = { file, slug: basename(file).replace(/\.md$/, ''), title: '', date: '', lots: [], captures: [], body: '', problems: [] };
+    const entry = { file, slug: basename(file).replace(/\.md$/, ''), title: '', date: '', lots: [], captures: [], alts: [], body: '', problems: [] };
     const m = FRONT.exec(text.replace(/^\uFEFF/, '')); // BOM des éditeurs Windows
     if (!m) {
         entry.problems.push('en-tête YAML absent (--- … ---)');
@@ -48,18 +92,10 @@ export function parseEntry(file, text) {
             entry.created = created.replace(' ', 'T');
     }
     entry.lots = list(head.lots);
-    entry.captures = list(head.captures);
     if (head.nocapture != null && String(head.nocapture).trim())
         entry.nocapture = String(head.nocapture).trim();
     entry.body = m[2].trim();
-    for (const c of entry.captures) {
-        // Copiées telles quelles sous le dossier de build : un chemin qui sort du dossier écrirait ailleurs.
-        if (isAbsolute(c) || c.split(/[\\/]/).includes('..'))
-            entry.problems.push(`capture hors du dossier des Nouveautés : ${c}`);
-        // Noms sages : utilisables tels quels dans une URL, et seulement des images.
-        else if (!CAPTURE.test(c))
-            entry.problems.push(`capture ${c} : image .png, .jpg, .webp ou .gif, nom en lettres, chiffres, « . _ - / »`);
-    }
+    Object.assign(entry, readCaptures(head.captures, entry.problems));
     if (!entry.title)
         entry.problems.push('title vide');
     if (!isDay(entry.date))
@@ -136,7 +172,7 @@ export function newEntry(dir, lots, rawTitle, today, now) {
     if (existsSync(path))
         throw new RafError(`${path} existe déjà`);
     mkdirSync(dir, { recursive: true });
-    writeFileSync(path, `---\ntitle: ${stringify(title).trimEnd()}\ndate: ${today}\ncreated: ${toStamp(now)}\nlots: [${lots.join(', ')}]\ncaptures: []\n# nocapture: raison, quand une capture n'a pas de sens\n---\nCe qui change pour l'utilisateur.\n`);
+    writeFileSync(path, `---\ntitle: ${stringify(title).trimEnd()}\ndate: ${today}\ncreated: ${toStamp(now)}\nlots: [${lots.join(', ')}]\ncaptures: []\n# une capture peut dire ce qu'elle montre : captures: [${CAPTURE_SHAPE.replace('chemin', 'captures/x.png')}]\n# nocapture: raison, quand une capture n'a pas de sens\n---\nCe qui change pour l'utilisateur.\n`);
     return path;
 }
 /**
@@ -210,7 +246,16 @@ export function newsData(project, entries, generated) {
     return {
         project,
         generated,
-        entries: entries.map((e) => ({ slug: e.slug, title: e.title, date: e.date, lots: e.lots, captures: e.captures, html: renderMarkdown(e.body) })),
+        entries: entries.map((e) => ({
+            slug: e.slug,
+            title: e.title,
+            date: e.date,
+            lots: e.lots,
+            captures: e.captures,
+            // Clé ajoutée seulement quand elle dit quelque chose : une entrée sans texte garde sa forme d'avant.
+            ...(e.alts.some(Boolean) ? { alts: e.alts } : {}),
+            html: renderMarkdown(e.body),
+        })),
     };
 }
 /** Écrit nouveautes.json, index.html et copie les captures sous `out`. */
@@ -237,7 +282,7 @@ function renderNewsPage(data) {
   <h2>${escapeText(e.title)}</h2>
   <p class="meta"><time datetime="${e.date}">${e.date}</time> · ${e.lots.map(escapeText).join(', ')}</p>
   ${e.html}
-  ${e.captures.map((c) => `<a href="${escapeText(c)}"><img src="${escapeText(c)}" alt="Capture : ${escapeText(e.title)}" loading="lazy"></a>`).join('\n  ')}
+  ${e.captures.map((c, i) => `<a href="${escapeText(c)}"><img src="${escapeText(c)}" alt="${escapeText(e.alts?.[i] || `Capture : ${e.title}`)}" loading="lazy"></a>`).join('\n  ')}
 </article>`)
         .join('\n');
     return `<!doctype html>

package/dist/plan.js

@@ -12,9 +12,15 @@ export function isOpen(status) {
 function escapeRe(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
+/**
+ * Ce qui ne peut pas suivre un identifiant cité : un point suivi d'un caractère de mot — « L1.4 » n'est
+ * pas le lot L1, « NC2.4 » n'est pas NC2 — alors que le point qui finit une phrase (« voir L1. ») passe.
+ * Même garde pour le format de raf et pour les identifiants d'un plan en lecture seule.
+ */
+const DOTTED = '\\.\\w';
 /** Matches `L3` or `L3/t1` as whole words. Group 1 = lot id, group 2 = task id. */
 export function refPattern(prefix) {
-    return new RegExp(`(?<![\\w/])(${escapeRe(prefix)}\\d+)(?:/(t\\d+))?(?![\\w])`, 'g');
+    return new RegExp(`(?<![\\w/])(${escapeRe(prefix)}\\d+)(?:/(t\\d+))?(?!\\w|${DOTTED})`, 'g');
 }
 export function extractRefs(text, prefix) {
     return [...text.matchAll(refPattern(prefix))].map((m) => ({ lot: m[1], task: m[2] }));
@@ -149,7 +155,7 @@ export class Plan {
                 ids: new Set(ids),
                 tasks: new Set(lots.flatMap((l) => l.tasks.map((t) => `${l.id}/${t.id}`))),
                 refs: ids.length
-                    ? new RegExp(`(?<![\\w/.-])(${ids.map(escapeRe).join('|')})(?:/([\\w-]+(?:\\.[\\w-]+)*))?(?![\\w-]|\\.\\w)`, 'g')
+                    ? new RegExp(`(?<![\\w/.-])(${ids.map(escapeRe).join('|')})(?:/([\\w-]+(?:\\.[\\w-]+)*))?(?![\\w-]|${DOTTED})`, 'g')
                     : null,
             };
         }
@@ -431,7 +437,11 @@ function asVerdict(raw) {
     if (!raw || typeof raw !== 'object')
         return undefined;
     const v = raw;
-    const verdict = { date: String(v.date ?? ''), verdict: String(v.verdict ?? '') };
+    // Écrit à la main sans verdict (clé absente, vide ou blanche) : rien n'a été dit de la revue, la porte
+    // reste fermée — comme `raf ux` et `raf review` refusent d'enregistrer un verdict vide.
+    if (String(v.verdict ?? '').trim() === '')
+        return undefined;
+    const verdict = { date: String(v.date ?? ''), verdict: String(v.verdict) };
     // Champ présent mais vide : relu « jusqu'à rien », comme un verdict noté sans commit.
     if ('commit' in v)
         verdict.commit = v.commit == null || String(v.commit).trim() === '' ? null : String(v.commit).trim();

package/dist/state.js

@@ -21,14 +21,17 @@ export function readNext(dir) {
     const lines = rest.map((l) => l.replace(/^- /, '')).filter(Boolean);
     return { date: head.replace(/^# /, '').trim(), lines };
 }
-/** Remplace les notes pour la prochaine session ; sans ligne, les efface. */
+/** Remplace les notes pour la prochaine session. Ne les efface jamais : c'est `clearNext`, demandé exprès. */
 export function writeNext(dir, date, lines) {
-    const file = join(dir, 'next.md');
-    if (lines.length === 0) {
-        rmSync(file, { force: true });
-        return;
-    }
-    writeFileSync(file, `# ${date}\n${lines.map((l) => `- ${l.replace(/\n/g, ' ')}`).join('\n')}\n`);
+    if (lines.length === 0)
+        throw new Error('writeNext : aucune ligne');
+    writeFileSync(join(dir, 'next.md'), `# ${date}\n${lines.map((l) => `- ${l.replace(/\n/g, ' ')}`).join('\n')}\n`);
+}
+/** Efface les notes pour la prochaine session ; rend celles qui s'y trouvaient, null s'il n'y en avait pas. */
+export function clearNext(dir) {
+    const previous = readNext(dir);
+    rmSync(join(dir, 'next.md'), { force: true });
+    return previous;
 }
 export function lockPath(dir) {
     return join(dir, 'deliver.lock');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sylad/cadence",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "A small, repo-native working method: a versioned plan linked to your commits, a changelog with screenshots, session rituals and deliveries proven by their effect.",
   "license": "MIT",
   "author": "Sylvain Ladoire",

package/skills/deliver/SKILL.md

@@ -51,7 +51,18 @@ Deliver one project at a time: the one the human names, or ask.
 4. On failure: read which step failed and why. Fix the cause, commit, push, deliver again. Never rerun
    blindly, never skip a check to make it pass.
 5. On success: `raf done <id>` (or the project's own tool when its plan is read-only) for the lots it lists **whose effect you have seen**; if one of them is
-   `visible`, `cadence news build` and deliver the news too.
+   `visible`, `cadence news build` and deliver the news too. With a read-only plan the list holds only
+   the lots that were in progress when the delivery started; the project's own tool has the last word
+   on what it marked delivered.
+6. After a green delivery that changes what a page shows or what it is served (screen, API, data
+   source, configuration of either) — in practice every delivery except docs-, plan- or tests-only
+   ones — have the `qa-reviewer` agent walk the delivered app in a real browser, whether the lot
+   is `visible` or not: give it the repository path, the base URL and the lot id. When the lot
+   touched only the backend, the agent starts with the pages that call the changed endpoints. It
+   checks each page against `docs/qa/expectations.md` — what the user must find there — and
+   reports a page left empty, an error shown, an API call that failed or came back empty: what
+   the checks of `cadence.yaml` do not see. Bring its blocking findings to the human. It is not a
+   gate: the delivery stays done, a finding becomes a new lot.
 
 ## Rules
 

package/skills/lead/SKILL.md

@@ -74,6 +74,20 @@ proposed sub-tasks back to the human.
 One project at a time, by the lead: push, then the `deliver` skill (`cadence deliver --dry-run`, then
 `cadence deliver`). Follow the human's standing instructions about confirmation before production.
 
+After a green delivery that changes what a page shows or what it is served (screen, API, data
+source, configuration of either) — in practice every delivery except docs-, plan- or tests-only ones
+— have the `qa-reviewer` agent check the delivered app, as a fresh subagent: give it the absolute
+path of the project, the base URL of the delivered app and the lot id. The lot need not be
+`visible`: a backend-only lot can empty a page without changing a screen. When the lot touched only
+the backend, the agent starts with the pages that call the changed endpoints. It walks the pages in
+a real browser against the project's expectations (`docs/qa/expectations.md`: per page, what the
+user must find there) and returns measured findings; it reads only, and never logs in. Bring its
+blocking findings back to the human — a page whose main content is missing, or that shows an error,
+is a defect even when the delivery checks are green — with its proposed follow-up lines. A project
+without an expectations file gets a draft back: show it to the human, who corrects it and decides
+whether it is committed. It is not a gate: `raf done` does not wait for it, and a finding becomes a
+new lot, not a reopened one.
+
 ## 5. Close
 
 At the end, the `session-close` routine in each project touched, and `cadence session next` lines in

package/skills/session-close/SKILL.md

@@ -24,6 +24,9 @@ With no project named, run `cadence session close` in each project touched durin
      otherwise `raf note <id> "where it stands, what blocks"`;
    - a commit without a lot that belongs to one → `raf note <id> "commits: <sha> …"`; nothing if it
      is genuinely outside the plan (docs, chores);
+   - a plan commit reported because it also touches a file generated from the plan (a published
+     plan) → propose to declare that file under `plan.files` in `cadence.yaml`; the files of a commit
+     decide whether it is plan upkeep, never its subject;
    - a finished lot marked `visible` without a news entry → `cadence news new <id>`, written for the
      user, with a screenshot;
    - a lot that `raf done` refuses, or that the check reports as finished, for lack of a review —
@@ -43,6 +46,8 @@ With no project named, run `cadence session close` in each project touched durin
 5. **Clean state**: everything committed and pushed, no delivery running. If the command still exits 1,
    say what remains and do NOT say the session is closed.
 6. **Three lines for next time**: `cadence session next "…" "…" "…"` — the next `session-start` shows them.
+   The lines replace the previous notes. Without a line the command refuses and keeps them; erase
+   them on purpose with `cadence session next --clear`, only when nothing is left to say.
 
 ## Do not