@sylad/cadence 1.8.0 → 1.10.0

package/docs/fonctionnement.md

@@ -12,7 +12,7 @@ box with a blue outline is where the work is kept or checked.
   <img alt="A lot goes from todo to doing, receives commits that cite it, gets its review and UX verdicts, becomes done, then is delivered by cadence deliver" src="fonctionnement-lot-light.svg">
 </picture>
 
-The plan (`docs/plan/raf.yaml`, or the file `cadence.yaml` names) is the single source of truth:
+The plan (`.cadence/raf.yaml`, the legacy `docs/plan/raf.yaml`, or the file `cadence.yaml` names) is the single source of truth:
 `raf check` reports every commit that cites no lot (unless a motivated `raf ignore` covers it).
 `hook.autostart` in `cadence.yaml` sets what the pre-commit hook does with a commit that cites a lot
 still `todo`: `warn` (the default), `refuse`, or `start` it in the same commit. `raf done` is refused
@@ -22,10 +22,10 @@ while a sub-task is open. A delivery is finished only when its effect checks pas
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="fonctionnement-wave-dark.svg">
-  <img alt="A lot without commits starts with a precheck (unless disabled), then by type through spec, mockup or sheet review and sealed acceptance tests, or straight to the implementation; then the UX pass if visible, the code review, corrections and an automatic raf review" src="fonctionnement-wave-light.svg">
+  <img alt="A lot without commits whose title cites a finding or another lot starts with a precheck (unless disabled), then by type through spec, mockup or sheet review and sealed acceptance tests, or straight to the implementation; then the UX pass if visible, the code review, corrections and an automatic raf review" src="fonctionnement-wave-light.svg">
 </picture>
 
-A lot without commits yet starts with the **precheck** (unless `orchestrate.precheck: false`; a lot that already has commits is never pre-checked): is the deliverable already there? « Yes » hands the lot back
+A lot without commits yet whose title cites a finding (`constat`, `revue`, `review`, `audit`) or another lot (its `goal:` counts like its title) starts with the **precheck** (unless `orchestrate.precheck: false`; a lot that already has commits, or whose title (or `goal:`) cites neither, is never pre-checked — L288; nor is a lot created after the last code commit of the repository whose title and `goal:` cite no lot that already has commits of its own, which has nothing to find — L322): is the deliverable already there? « Yes » hands the lot back
 to the lead; « partial » passes what exists to the implementation. Then:
 
 - `screen: page` only: **spec** (mockup and screen sheet), **mockup review** (`ux-reviewer`, two
@@ -73,7 +73,7 @@ working repository's `dist/`: they read a separate worktree under `~/.local/shar
 only by `npm run service -- <sha>`. The command refuses a sha that is not an ancestor of `HEAD` and a
 sha whose cited lots are not `done`, so a wave cannot put unreviewed code in service. In the
 working repository, `npm run build` is a typecheck only. A `dropped` lot whose every commit is undone
-by a `git revert` under the sha no longer blocks.
+by a `git revert` under the sha no longer blocks. The command keeps the copy in service and the 3 put in service before it (rollback), removes the older ones unless a live process still uses one, and says what it purged (number of copies, space freed).
 
 ## Budget of a lot
 
@@ -81,7 +81,7 @@ The budget a wave gives a lot is derived from its estimate, measured on the runs
 
 | Lot | Budget |
 |---|---|
-| up to 0.5 day | 540 k tokens |
+| up to 0.5 day | 600 k tokens |
 | 0.5 to 1 day | 750 k |
 | beyond | 570 k per day, 750 k at least |
 | `screen: page` | 1.3 M at least, or the ordinary budget + 450 k if that is more |
@@ -96,7 +96,7 @@ The final review is always played; the budget bounds the writing passes. A `scre
 
 - **Session cap.** As many sessions or subagents running at once as the cap (2 by default, set by the
   human with `CADENCE_MAX_SESSIONS` or `--max-sessions`). The lead never raises it itself.
-- Never two sessions in the same repository at the same time.
+- Never two sessions in the same repository at the same time. (The worktree mode, `orchestrate.worktrees: true` — on in cadence's own `cadence.yaml`, off where the key is absent — lets two independent lots of one repository play at once, each in its own worktree — [docs/orchestrate.md](orchestrate.md#one-worktree-per-lot-orchestrateworktrees-l279).)
 - A session cannot ask the human anything: it stops and reports, and the lead brings the question back.
 - A sealed acceptance test that contradicts its sheet is corrected by the lead with
   `cadence spec reseal <lot> <test> --reason "…"`, never by editing `acceptation.json`.

package/docs/lead.md

@@ -10,7 +10,7 @@ summaries, decides with the human, and leaves the work to fresh short sessions r
   <img alt="The lead workflow in three lanes (human, lead session, orchestrate program and agents), from the tour of the projects to the close of the session" src="lead-workflow-light.svg">
 </picture>
 
-Dashed boxes are conditional steps: the precheck runs only for a lot without a commit yet (unless `orchestrate.precheck: false`), and the spec, sheet review and accept steps run only for a `screen: page` lot or a `spec: true` lot. The skill itself is `skills/lead/SKILL.md`; this page is its
+Dashed boxes are conditional steps: the precheck runs only for a lot without a commit yet whose title cites a finding (`constat`, `revue`, `review`, `audit`) or another lot (unless `orchestrate.precheck: false`), and the spec, sheet review and accept steps run only for a `screen: page` lot or a `spec: true` lot. The skill itself is `skills/lead/SKILL.md`; this page is its
 picture, not its source.
 
 ## The steps
@@ -20,9 +20,10 @@ picture, not its source.
    quick wins. It stops and waits: the human picks the lots and the order (`--priority`, or the
    `priority:` list of the parent folder's `cadence.yaml`).
 2. **Wave.** The lead starts `cadence orchestrate <project>:<lot> … --wave <id>` in the background.
+   When a lot's title is stale, the lead does not delegate by hand: it passes `--goal "…"` (one lot per launch), or writes a `goal:` key on the lots in the plan (several lots at once) — in the native plan as `goal:`, in a plan kept by another tool (read-only) by mapping its key with `plan.fields: { goal: <their key> }` in `cadence.yaml` — which replaces the title as the objective of the briefs (L258, [orchestrate](orchestrate.md)).
    For each lot the program runs, in fresh sessions and in this order: `precheck → spec → maquette →
-   accept → implement → review → ux`. The **precheck** applies to any lot without a commit yet (unless
-   `orchestrate.precheck: false`). The spec steps exist only for a lot that declares
+   accept → implement → review → ux`. The **precheck** applies to a lot without a commit yet whose title cites a finding (`constat`, `revue`, `review`, `audit`) or another lot (unless
+   `orchestrate.precheck: false`; L288). The spec steps exist only for a lot that declares
    a `screen:` of `page` (a visible lot that creates or changes a whole screen; `screen: component` and `screen: journey`
    lots take the ordinary path, straight to the implementation, unless they already have a sheet) or `spec: true` (a lot without a screen
    that still has a behaviour to pin down: `precheck → spec → fiche → accept → implement → review`);
@@ -52,7 +53,9 @@ picture, not its source.
 3. **Relay.** The lead follows the wave's journal (`tail -n +1 -F .cadence/runs/<id>/journal.log`, one
    line per transition) and tells the human each line in one sentence, with no polling loop. A
    question from a session comes back to the human at once; the answer goes in with
-   `cadence orchestrate --resume --answer <project>:<lot> "…"`. The lead never answers in the
+   `cadence orchestrate --resume --wave <wave> --answer <project>:<lot> "…"` (the wave is named: the
+   command is printed under each question of the table, ready to run; without a wave, `--resume` is refused as
+   soon as the folder keeps several unfinished waves). The lead never answers in the
    human's place. `--drop` and `--stop-after-current` steer a wave that is running.
 4. **Review.** The final table of the wave lists the lots ready, handed back, and the line
    « livrable jusqu'à <sha> » for a ready lot stacked under a handed-back one. Minor findings come back in
@@ -62,7 +65,7 @@ picture, not its source.
    UX reviewer's captures: the lead records `raf ux` on the human's verdict, never on its own — unless the parent folder's `cadence.yaml` says `lead.ux: lead`: then the lead forms the verdict from the reviewer's report and its own look at the captures, and asks the human only at the slightest doubt. Then
    `raf done`.
 6. **Delivery.** Push (for a « livrable jusqu'à <sha> », that sha alone, never HEAD), then
-   `cadence deliver`. After a green delivery that changes what a page shows or what it is served, the
+   `cadence deliver`. A lot that turns ready is delivered while the wave runs (`cadence deliver --sha <sha>`, accepted when no commit of the sha belongs to a lot that is not ready), not at the end of the wave. After a green delivery that changes what a page shows or what it is served, the
    `qa-reviewer` agent walks the delivered pages in a real browser, reads only, and brings its blocking
    findings to the human. It is not a gate: a finding becomes a new lot.
 7. **Threshold and chaining.** Before every new wave the lead reads `cadence session context`. Under
@@ -79,9 +82,9 @@ picture, not its source.
 
 | Rule | Why |
 |---|---|
-| At most **as many subagents as the session cap** running at once (2 by default; the human sets it with `CADENCE_MAX_SESSIONS`), orchestrate sessions included | `cadence orchestrate --status` and `cadence lead tour` print `créneaux libres : N sur M`, M being the configured cap; the lead never raises `--max-sessions` or `CADENCE_MAX_SESSIONS` itself |
-| Never two sessions in the same repository at the same time; the lead does not commit where a wave runs | a wave's lock refuses `cadence deliver` while a lot still works there |
-| A locked acceptance test that contradicts the sheet is corrected by the lead with `cadence spec reseal <lot> <test> --reason "…"` (lot in progress, outside a wave; an amended sheet is accepted once committed, every commit that touched it citing the lot, L217, never put it back to the red state; a delivered lot with an unstable test: add `--porteur <lot in progress>`, L212), then `--resume --answer` for a lot in question, or a new `cadence orchestrate <project>:<lot>` for a lot handed back (`--resume` skips it) | never by a session, never by editing `acceptation.json` |
+| At most **as many subagents as the session cap** running at once (2 by default; the human sets it with `CADENCE_MAX_SESSIONS`), orchestrate sessions included | `cadence orchestrate --status` and `cadence lead tour` print `créneaux libres : N sur M`, M being the configured cap and the sessions the lead started by hand (`cadence lead hold`, L255) being subtracted; the lead never raises `--max-sessions` or `CADENCE_MAX_SESSIONS` itself |
+| Never two sessions in the same repository at the same time; the lead does not commit where a wave runs (with `orchestrate.worktrees: true` two lots of one repository play at once, each in its own worktree: not a rule for the lead) | a wave's lock refuses `cadence deliver` while a lot still works there |
+| A locked acceptance test that contradicts the sheet is corrected by the lead with `cadence spec reseal <lot> <test> --reason "…"` (lot in progress, outside a wave and with no wave that is not `done` keeping open a lot of the repository still `doing` in its plan, the resealed lot or another, e.g. a question waiting: `--resume --wave <wave> --answer` or `--drop` first, the one error lists every wave concerned, the live one that holds the lock (to wait for) and the stopped ones, and gives for each stopped wave the single `cd <launch folder> && cadence orchestrate --resume --wave <wave> --drop <project>:<lot> [--drop …]` to run, a `--drop` per open lot of the repository in that wave, the queued ones that are not `doing` in the plan included, since `--resume` would relaunch them and they would take the lock back, L238 L239; an amended sheet is accepted once committed, every commit that touched it citing the lot, L217, never put it back to the red state; a delivered lot with an unstable test: add `--porteur <lot in progress>`, L212), then a new `cadence orchestrate <project>:<lot>` for a lot handed back (`--resume` skips it) | never by a session, never by editing `acceptation.json` |
 | Deliveries and the `raf ux` / `raf review` verdicts belong to the lead, one project at a time | never to a subagent, never two deliveries in parallel |
 | The UX verdict is the human's unless `lead.ux: lead` (parent `cadence.yaml`, default `human`) | then the lead decides from the report and the captures, and brings any doubt to the human |
 | A session cannot ask the human anything | it stops and reports; the lead brings the question back |
@@ -107,33 +110,57 @@ The mechanics around it (the life of a lot in the plan, a lot inside a wave, put
 [fonctionnement.md](fonctionnement.md). See also the [lead tour](lead.md#lead-tour) section below and the [orchestrate](orchestrate.md#orchestrate)
 page.
 
+## lead hold and release
+
+`cadence lead hold <label> [--ttl minutes]` and `cadence lead release <label>` (L255) declare the sessions the lead starts by hand — a fix subagent, a review, a QA pass launched outside an orchestrated wave. No wave carries such a session, so the slot registry could not see it: on 2026-10-23 the lead ran 4 sessions under a cap of 3 while `créneaux libres` said one slot was free. `hold` registers the session under its label for `--ttl` minutes (an integer ≥ 1, 60 by default; holding the same label again renews it instead of counting twice); `release` hands it back (releasing a label that is not held answers `aucune session « <label> » inscrite` and exits 0). A hold whose time has run out stops counting, but is not forgotten: nothing stops the session (L278), so `cadence lead tour` and `cadence orchestrate --status` print `⚠ session du lead échue : <label> (inscrite depuis 5 h 10 min, échue depuis 2 h 10 min) — la reprendre (cadence lead hold <label> --ttl <minutes>) ou l'arrêter (cadence lead release <label>)` after the slots line, and the `cadence-hud` band shows the same ⚠ row, until the lead renews the hold or releases it (an expired hold nobody touched is dropped 24 h after its expiry). The `--ttl` is therefore the maximum duration declared for the session; the `lead` skill says to renew or stop it at each ⚠. The line is not part of `--json`.
+
+The held sessions are kept in the `holds/` folder of the cadence home (`CADENCE_HOME`, shared by every folder and every wave). While at least one is held, the line of the live waves of `cadence orchestrate --status` and of `cadence lead tour` gains a segment and subtracts them: `vagues en cours : 1 · sessions en cours : 0 · sessions du lead : 1 (correctif-L12) · créneaux libres : 0 sur 3`. A held session alone is enough to print the line (`vagues en cours : 0`). It is a display, like the rest of the slots line: a hold blocks no session and never raises the cap (a wave that is already running keeps its own slot counting), and the `lead` skill declares every hand-started session with it.
+
+## The librarian by hand
+
+For a lot the lead delegated by hand, `raf check` or the `dérive` column of `cadence lead tour` reporting `documentation en retard` is
+handled before the review, as an orchestrated wave does it: the lead hands the project (absolute path) and the lot id to the
+`doc-keeper` agent ([skills](skills.md), [news](news.md#the-librarian-doc-keeper)), in a writing session, or read-only when it
+only wants the list of the documents to change (L306). A document outside the repository is named by the `docs.articles` key
+of the project's `cadence.yaml`, never guessed: the lead reads that key itself and puts its entries in the brief with the absolute path of each repository (the subagent is given read access to it), because the agent examines no outside document the brief does not name. The agent proposes a lot for the plan of that repository, in the `resume` of its
+report, and the lead decides whether to add it (`raf add` in that repository). The agent never writes to that plan.
+
 ## lead tour
 
 `cadence lead tour [folder] [--idle 3] [--depth n] [--json]` is the lead's morning table, with no model in
 the loop. From a parent folder (default: the current one) it takes every direct sub-folder that
-holds `docs/plan/raf.yaml`, or a `cadence.yaml` with a `plan:` key (a plan kept by another tool
-included), and for each one reads the same facts as `cadence session start` — in-process, no
+holds `.cadence/raf.yaml` or `docs/plan/raf.yaml`, or a `cadence.yaml` with a `plan:` key (a plan kept by another tool
+included; hidden folders, `node_modules` and `tmp/` — throwaway working copies — are skipped), and for each one reads the same facts as `cadence session start` — in-process, no
 sub-process, no call to `claude` — then prints **one line per project**:
 
 ```
-alpha · en cours L1 (silencieux 4j) · dérive 1 (✗ L2 a 1 commit(s) mais est encore todo) · notes : finir L1 puis livrer · prochain L3 Typo · dépôt non commité, non poussé
+alpha · en cours L1 (1 commit, silencieux 4j) · dérive 1 (✗ L2 a 1 commit(s) mais est encore todo) · notes : finir L1 puis livrer · prochain L3 Typo · dépôt non commité, non poussé
 beta · en cours rien · dérive aucune · notes : aucune · prochain T2 Second · dépôt propre
 ```
 
 | Column | Content |
 |---|---|
-| `en cours` | ids of the lots in progress; `(aucune activité)` when it has none at all, `(silencieux Nj)` when the lot's last activity (commit, note or start) is more than `--idle` days old (default 3) |
+| `en cours` | ids of the lots in progress, each with its number of commits (`0 commit` included: a close note on a lot without commit is not « done, `raf done` forgotten »); then `aucune activité` when it has no activity at all, `silencieux Nj` when the lot's last activity (commit, note or start) is more than `--idle` days old (default 3) |
 | `dérive` | the gaps `raf check` reports (a lot whose commits leave a document behind, [`docs.sync`](news.md#documentation-that-follows-the-code), included), counted and the first two shown |
 | `notes` | the notes left by the last `session close`, joined with ` / ` and cut at 120 characters |
 | `prochain` | the first ready lot (quick wins first) — id and title cut at 60 characters; a lot whose [`gate`](raf.md#plan-file) is not met is not ready |
 | `attend` | only when a lot waits on its `gate`: `attend L190` |
 | `dépôt` | `non commité` (modified or untracked files), `non poussé` (commits ahead of the upstream), `livraison en cours` (live delivery lock); `propre` otherwise |
 
+After them, one line per project that does not declare `orchestrate.test` (L327): `alpha · porte de tests absente : orchestrate.test n'est pas déclaré, la vague ne lancera pas la suite (seule la revue le fera si elle le décide) · commande probable : npm test (à déclarer en orchestrate.test)`. The probable command is read from `package.json` (`scripts.test`), `pyproject.toml` (pytest) or `pom.xml` (`mvn test`) and omitted when none exists; the lead declares `test:` and `build:` in that project's `cadence.yaml` after checking the command is green, one config commit per project. `--json`: `noTest: { probable }` on the project's row, absent when the key is declared. Same line in [`orchestrate --dry-run`](orchestrate.md).
+
+After the project lines the tour lists the **worktrees kept by waves** (L279, `orchestrate.worktrees: true`, on by default in cadence since L320; [`orchestrate.worktrees`](orchestrate.md#one-worktree-per-lot-orchestrateworktrees-l279)): a title, then one line per kept worktree — repository, lot, age, number of unintegrated commits, path — so that a lot handed back with unintegrated commits is never forgotten; nothing is printed when there is none (`--json`: `worktrees` on the project's row). `cadence orchestrate --status` and the final table of a wave print the same lines; the lead removes one with `cadence orchestrate --remove-worktree <project>:<lot> [--abandon-commits]`.
+
 Before the project lines the tour prints the **perf header** (L227): one line per `⚠` of `cadence perf` for the folder, in the order of `perf`, each ending with its decision and, for a trend, the value of its quality twin (speed and quality side by side); the net-bottleneck `⚠ goulot` line is relayed as is. Nothing is printed when no `⚠` stands, and the output is then the one of a tour without header. The header is read with `perf`'s own reading of the folder (projects up to two levels, whatever `--depth`) and only in the text output: `--json` is unchanged. When `perf` cannot read the folder (no `.cadence/runs`, malformed price grid, unreadable journals or plans) the tour prints no header, reports no perf error and exits 0. The [lead skill](skills.md) reads the header before proposing the three lots and opens an improvement lot only on a trend confirmed on two windows or a net bottleneck.
 
-When an orchestrated wave is live, one more line closes the tour (not part of `--json`): `vagues en cours : 1 · sessions en cours : 0 · créneaux libres : 1 sur 2` — the lead reads the free slots there instead of computing them (L141). The `sur M` is the cap the human set (`CADENCE_MAX_SESSIONS`, 2 by default), not a fixed 2 (L208); an invalid value falls back to 2 in this display.
+When an orchestrated wave is live, one more line closes the tour (not part of `--json`): `vagues en cours : 1 · sessions en cours : 0 · créneaux libres : 1 sur 2` — the lead reads the free slots there instead of computing them (L141). The `sur M` is the cap the human set (`CADENCE_MAX_SESSIONS`, 2 by default), not a fixed 2 (L208); an invalid value falls back to 2 in this display. The sessions held with [`lead hold`](#lead-hold-and-release) are subtracted from the free slots, and one alone is enough to print the line (L255).
+
+Next to it, when at least one ready lot is free, a line `prêts, ressources libres : alpha:L3 <title> · beta:L2 <title> (banc)` (L252, GitHub issue #13, 2/3) lists, for every project of the tour, the ready lots (same rule as `next`, minus the ones marked « à décider ») that can start now: a lot is free when none of the resources in its `uses:` (shown in parentheses) is held by a lot `doing` in any project of the tour or in any project that shares its resources (the projects under the folder whose `cadence.yaml` declares `resources:`, walked with that file's `depth:`, one level by default, so `P/x` and `P/grp/alpha` share the `banc` of `P/cadence.yaml` with `depth: 2` wherever the tour is launched from, even from inside one project; with no declared resource, the projects of the parent folder), nor by an unfinished lot of a live wave (a wave's lot is recognised by its repository and its id, not by the project name: a nested project `grp/alpha` matches the wave launched from `grp/` that cites it as `alpha`, and a wave launched from another folder only hides the lots of its own repositories); a lot with no `uses:` holds none and is always free. The line shows at most 3 lots per project, then `alpha +K` for the others. Like the slots line it prints while a wave is live, or as soon as a session is held with `lead hold` (L255); with neither, it stays silent. It is a display: nothing locks, `raf start` and `orchestrate` still start a lot whose resource is taken. `--json` gives the same lots, always, as a `free` array on each project (`id`, `title`, and `uses` when the lot has any; absent when the project has none).
+
+The `lead` skill (L253, GitHub issue #13, 3/3) tells the lead to read that line again each time an agent comes back and each time a lot is blocked, before waiting: a lot it lists can start at once, with the free slots line saying a slot is free, instead of waiting behind the blocked one. The line never raises the slot cap.
 
 `--json` prints the same content as an array of objects (`project`, `doing`, `drift`, `notes`, `waiting` (only when a lot waits on its `gate`),
+`free` (L252, above),
 `next`, `repo`, and `error` when the project could not be read), plus `progress` — `{ done, doing, todo, added7 }`,
 the lots done / in progress / to do (dropped and recurring lots left out) and those created in the last 7 days (L149), which
 [`cadence-hud`](../plugins/cadence-hud/README.md) draws as one progress bar per project. Projects come in the order of the

package/docs/news.md

@@ -150,10 +150,39 @@ to be reported as one **major** finding per line — a stale document is not lef
 memory of a sentence. Touching a document is what the program checks; whether its text is true is
 still the review's reading. The commits of neighbouring repositories (`repos:`) are not audited.
 
+A gap is closed by writing the document, or **acknowledged** when the documents really stay true: `raf docs-ok <lot> --reason "why"` (L317; the reason is required) writes a dated `docs_ok:` key on the lot, which `raf check`, `cadence lead tour` and `cadence orchestrate` all read. There is no silent third way: a lot with an open gap does not end ready in a wave.
+
+### The librarian: `doc-keeper`
+
+`docs.sync` says *that* a document is behind; the `doc-keeper` agent (L306, `agents/doc-keeper.md`, generic: it knows no
+folder and no project) says *which* passage and writes it. Given a repository and a lot, it reads the diff of the lot
+(the commits that cite it), draws the map of the project's documents (the `docs.sync` rules, the README, the pages of
+`docs/`, the CHANGELOG, the news entries, the architecture document), lists the documents the change makes false or leaves
+out, then:
+
+- **writing session**: updates them and commits with explicit paths and `docs(<lot>): …`;
+- **read-only session** (no write tool, or a brief that says so): changes nothing and lists, document by document, the
+  passage to write.
+
+**Where it writes** (L326): a lot that changes how the tool works is written in the pages of `docs/`, in full.
+The README is a short home page: it receives only a link to that page, never the detail (an option, a key, a path, a flag).
+The test `readme-accueil` holds the README to that (size, short lines, no detailed option).
+
+`cadence orchestrate` calls it by itself when `docs.sync` reports a document behind the commits of the lot, **before the
+review** (see « Librarian before the review » in [orchestrate](orchestrate.md)); the lead calls it by hand otherwise
+([lead](lead.md)).
+
+A document **outside the repository** is the librarian's only when the configuration names it, with the key that already
+names the project's article elsewhere, `docs.articles` (see below; absent by default): « this project is also described
+by this file of that repository ». The librarian reads that file (its repository is opened to the session for reading, and
+the brief gives its absolute path) and, when the change makes it false, **proposes a lot** for the plan of that repository
+(a title, then the file, the passage and the sentence to change) in the `resume` of its report, starting with
+« lot proposé ». It never edits that file and never writes to that plan: the lead decides whether the lot enters it.
+
 ### An article elsewhere that follows the delivery
 
 A case study that lives in a neighbouring repository (the project's article on a showcase site) goes stale
-the same way. `docs.articles` names it:
+the same way. `docs.articles` names it (`repo` absolute, or relative to the project):
 
 ```yaml
 docs: