@sylad/cadence 1.15.1 → 1.17.0

package/docs/session.md

@@ -3,7 +3,7 @@
 # session
 
 ```sh
-cadence session start              # notes from the last close, lots in progress (commit count, `0 commit` included, and last activity; silent ones flagged),
+cadence session start              # notes from the last close, lots in progress (work commit count, `0 commit` included — plan commits are not counted, as in `raf commits` — and last activity; 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`,
@@ -26,7 +26,7 @@ cadence session context            # `ctx 42 % (84000/200000)`: the context of Y
 `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
+point), it still reports since that opening instead of an empty period. The period journal (`Fait depuis`, `Commits de la période`) lists work commits only: plan commits (`plan: L1 démarré`) are left out, as in `raf commits`. 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.)
 

package/docs/whats-new.md

@@ -4,6 +4,9 @@
 
 ## In two lines
 
+- **1.17.0**: `cadence orchestrate` refuses a repository holding a `.git/index.lock`; `raf docs-ok` works on a plan kept by another tool; `cadence verify --gate` replays a red test alone, like the gate of a wave.
+- **1.16.1**: publishes 1.16.0 (tagged, never published), plus `raf gantt` counting commits without plan commits, one login check per `orchestrate --continue` launch, and a wider `CHANGELOG.md` conflict settled by worktree integration.
+- **1.16.0**: easier arrival for a team already equipped and for a new user: a `docs/with-your-tools.md` page, `raf --version`, no gap after `raf init`, Claude Code login checked before any write, commit counts without plan commits.
 - **1.15.1**: a getting-started page (`docs/quickstart.md`) takes a lead of several projects from install to the first wave and lists the usual stops; GitHub issue templates for bugs and requests; a contrast fix in the dark figure.
 - **1.15.0**: worktree integration settles the `CHANGELOG.md` conflict by itself; `--integrate` accepts a lot corrected and reviewed outside the wave; `raf ignore` clears a plan commit citing lots; `raf done` gives the plan commit.
 - **1.14.1**: publishes 1.14.0 (tagged, never published): Node 22.18 or later is required; `plan.commit`, `plan.onWrite`, `orchestrate.testReplay`, `spec green`, `ref coverage` and `verify --gate --sha`.
@@ -37,6 +40,12 @@ Each is a paragraph in [docs/whats-new.md](whats-new.md) and a full section in [
 
 The long form of « In two lines » above (the README no longer carries a « What's new » section since L326: it links here). The full history, with the date of each version, is in [CHANGELOG.md](../CHANGELOG.md).
 
+**1.17.0**: fewer stops that were not the lot's fault. `cadence orchestrate` and its `--dry-run` refuse a repository holding a `.git/index.lock` before writing anything (L385, `docs/orchestrate.md`): the message gives the age of the lock, whether a git process is running, and the `rm` command to remove a stale one. A plan commit that fails (stale lock, refusing hook) now puts the plan back as it was even when the lock blocks the index, where the next lot used to be handed back as a « dépôt sale ». `raf docs-ok` no longer refuses a plan kept by another tool (read-only): the acknowledgement of a `docs.sync` gap is written to `.cadence/docs-ok.yaml` (`L12: { date, reason }`, next to the project's `cadence.yaml`), the plan is never touched, and `raf check`, `raf show`, `cadence lead tour` and `cadence orchestrate` read it; the librarian's brief names that file to commit (L386). `cadence verify --gate` applies `orchestrate.testReplay` like the gate of a wave (L387, `docs/deliver.md`): a red test the output names is replayed alone, twice at most, and a test that passes alone is reported as unstable under load instead of turning the gate red. A red step that names no test prints the last 10 lines of its output, prefixed `  | `. The gate and the replay get `CADENCE_TEST_WORKERS` like a wave's gate (the caller's value, else cores ÷ `CADENCE_MAX_SESSIONS`), so `--maxWorkers=$CADENCE_TEST_WORKERS` works from a plain shell, and a red step says that a replay took place and how many tests it confirmed green.
+
+**1.16.1**: 1.16.0 was tagged but never published: a test added with it (R2 of L377) supposed `raf` installed in the `PATH`, found it on the developer's machine and not on the runner, and the publish run went red, a fault of the test and not of the tool (L384); 1.16.1 publishes it as it stands, so everything listed under 1.16.0 below arrives with it. The test suite no longer depends on a `raf` or a `cadence` installed on the machine (L384, `docs/releasing.md`): the test now has its hook run `raf` from the sources, and the suite removes every installed `raf` and `cadence` from the `PATH` of the tests (the other tools stay), so such a test is red on the lead's machine and in the gate, not only at publication. `raf gantt` counts the commits of a lot as `raf commits` does (L381, `docs/raf.md`): plan commits no longer inflate the commit column nor the tooltip of a bar, a lot whose only commit is `plan: L1 démarré` reads 0, and the filter reads the files of the commits in one `git log` call instead of one `git diff-tree` per commit (about 20 s down to 2 s on 2,700 commits for the Gantt page); a test now holds the same count for `cadence session start` and `close`, and the test that held `raf now` to the lots it shows can now fail. With `--continue`, `cadence orchestrate` reads `claude auth status` once per launch instead of again, up to 20 s each, for every candidate lot of every round (L382, `docs/orchestrate.md`), and the message quoted in `docs/quickstart.md` and `docs/orchestrate.md` no longer nests backticks inside backticks, which broke the Markdown rendering. The worktree integration of `cadence orchestrate` also settles a `CHANGELOG.md` conflict where one lot adds a section under `[Unreleased]` (`### Fixed`) with its entry and the other a bare entry (L383, `docs/orchestrate.md`): the bare entry is filed under the section the other side added, one section title and one entry per lot, instead of handing the lot back; with no single section to file it under, the conflict stays by hand.
+
+**1.16.0**: easier arrival, for a team that already has its tools and for someone who has never used cadence. A new page, `docs/with-your-tools.md` (L363, a short section of the README), is written for teams that already have a tracker, a `HANDOFF.md`, ADRs and a commit convention: what cadence does not replace, what is optional (`raf`, `session start|close`, the hook), what plugs into what you have (a plan kept by another tool, read-only, with your own ticket ids; `plan.commit` for the subject of the plan commits, which by default still read `plan: L12 démarré (orchestrate …)`, GitHub issue #15, L375; `docs.sync` for your docs) and what it adds (waves with an automatic review, a deliver that verifies the effect), with a figure. The other changes come from the walkthrough of a new user. `raf --version` and `raf -v` print the version, as `cadence --version` does, instead of `Unknown option '--version'` (L376, only as the first argument: `raf show --version` stays an unknown option), and `cadence orchestrate alpha:L1` launched from inside `alpha` says why the folder is not found (the project is a sub-folder of the current folder; inside a repository `.:L1` works). The commit that follows `raf init` no longer opens a « commit sans lot » gap (L377, `docs/raf.md`, `docs/quickstart.md`): what `raf init` writes and a `cadence.yaml` created in the same commit with only `plan:` and `orchestrate:` keys count as plan files, while a code file, another `.gitignore` line, a `deliver:` key or a later edit of `cadence.yaml` keeps it a gap, and the getting-started page drops its `raf ignore` workaround. `cadence orchestrate` checks that Claude Code is logged in (`claude auth status`) before starting a lot (L378, `docs/orchestrate.md`): when it is not, the command is refused before any write to the plan (no `raf start`, no commit, the lot stays `todo`) and the message says to run `claude` then `/login`, `--dry-run` reports it with a `⚠`; before, the lot was started and failed at the first session with `Not logged in`, left `doing`. `raf now`, `cadence lead tour` and `cadence session start` count the commits of a lot as `raf commits` does (L379, `docs/raf.md`, `docs/lead.md`, `docs/session.md`): plan commits, which touch only plan files, are left out, so a lot just started reads `0 commit` instead of `1 commit(s)` while `raf commits` lists nothing, and the period journals of `session start` and `session close` leave them out too. `cadence release` prints `cadence verify --gate --sha HEAD` right after the version commit, before the plugin evaluation and the tag, so the suite runs on the commit that will be published (L380, `docs/releasing.md`), and the tests that look for the entry of a lot in `CHANGELOG.md` read the section that carries it, not `[Unreleased]` alone, which the version commit empties, a fault that had stopped the release of 1.14.0 and again the next one (a guard test refuses the pattern).
+
 **1.15.1**: a way in for a lead who has never used cadence. A new getting-started page, `docs/quickstart.md` (L358, a section of the README), goes from install to the first wave: the parent folder, `raf init` in each project with the minimal `cadence.yaml`, the tour, `/cadence:lead`, the first wave, and a table of the usual stops (no Node, `EACCES`, no git identity, Claude Code not logged in). It comes from a walkthrough measured on a clean machine. Two GitHub issue templates, bug and request, are forms (L358, `.github/ISSUE_TEMPLATE/`); a `config.yml` turns off blank issues and points to the getting-started page, and the bug form asks for `cadence --version`, the steps and what was printed. The dark getting-started figure (`docs/quickstart-dark.svg`) draws the grey texts of « Lead session » in a lighter grey, 4.26:1 on the blue before and now above the 4.5:1 of WCAG 2.2 AA, and `docs/overview.md` lists `docs/quickstart.md` in its map of the pages (L374).
 
 **1.15.0**: fewer lots handed back, and fewer manual detours, on the lead's side. The integration of `cadence orchestrate` in worktree mode no longer hands a lot back for a `CHANGELOG.md` conflict when the branch was released while the lot lived (L369, `docs/orchestrate.md`): an entry that the release moved under the published version is no longer read as a removal, and the entries a lot's commits wrote then reworded are dropped in favour of the version at the tip of the lot's branch, so one final entry per lot is left. `cadence orchestrate --resume --integrate <project:lot>` now accepts a lot handed back for its budget or a non-compliant review that the lead corrected and reviewed outside the wave (L370, `docs/orchestrate.md`, `docs/lead.md`): fix in the worktree, `raf review` there with the plan committed there, then `--integrate`; the lot restarts at the integration step with that verdict instead of the refusal « le lot n'est pas rendu à l'étape d'intégration ». A review older than a commit of the lot, or none, keeps the refusal. If the lead also wrote on that lot in the repository's plan meanwhile, the plan conflict of the rebase is settled by the program, provided that plan commit adds nothing but lot reviews. `raf ignore` also acknowledges a commit that cites known lots (L372): a plan commit that creates lots or cites a setting in parentheses was counted as work on those lots and could not be cleared; an acknowledged commit now counts for no lot, `raf commits` no longer lists it, and `raf check --ignored` does. `raf done <lot>` says that it did not commit the plan (L371): it never has, `raf` only writes the plan file, so when the plan or a file `plan.onWrite` produces has changes, the message prints the `git add` and `git commit` that take them, the subject following the project's `plan.commit` template.

package/docs/with-your-tools-dark.svg

@@ -0,0 +1,41 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1010 290" width="1010" height="290" role="img" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif" font-size="13" fill="#e6edf3">
+<title>cadence next to the tools you already have</title>
+<desc>Your tools stay as they are: the tracker, HANDOFF.md, the ADRs and your commit convention. The plan can be read from your tracker's file, the plan commits follow your format and your docs are kept in step. On top, cadence adds orchestrated waves with an automatic review, and a deliver that verifies the effect.</desc>
+<defs><marker id="arw" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 z" fill="#8b949e"/></marker></defs>
+<rect width="1010" height="290" fill="#0d1117"/>
+<text x="20" y="22" font-weight="600" font-size="13.5" fill="#e6edf3">1. Your tools (kept)</text>
+<rect x="20" y="36" width="290" height="52" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="165" y="57" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">Linear, Jira</text>
+<text x="165" y="74" text-anchor="middle" font-size="11.5" fill="#8b949e">tickets, board, assignment</text>
+<rect x="20" y="98" width="290" height="52" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="165" y="119" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">HANDOFF.md</text>
+<text x="165" y="136" text-anchor="middle" font-size="11.5" fill="#8b949e">your hand-over notes</text>
+<rect x="20" y="160" width="290" height="52" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="165" y="181" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">ADRs</text>
+<text x="165" y="198" text-anchor="middle" font-size="11.5" fill="#8b949e">your decisions</text>
+<rect x="20" y="222" width="290" height="52" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="165" y="243" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">Conventional Commits</text>
+<text x="165" y="260" text-anchor="middle" font-size="11.5" fill="#8b949e">your commits</text>
+<text x="360" y="22" font-weight="600" font-size="13.5" fill="#e6edf3">2. What plugs in</text>
+<rect x="360" y="36" width="290" height="52" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="505" y="57" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">plan: read-only</text>
+<text x="505" y="74" text-anchor="middle" font-size="11.5" fill="#8b949e">your tracker export is the plan</text>
+<rect x="360" y="98" width="290" height="52" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="505" y="119" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">plan.commit</text>
+<text x="505" y="136" text-anchor="middle" font-size="11.5" fill="#8b949e">plan commits in your format</text>
+<rect x="360" y="160" width="290" height="52" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="505" y="181" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">docs.sync</text>
+<text x="505" y="198" text-anchor="middle" font-size="11.5" fill="#8b949e">your docs kept in step</text>
+<rect x="360" y="222" width="290" height="52" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="505" y="243" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">commit-msg hook</text>
+<text x="505" y="260" text-anchor="middle" font-size="11.5" fill="#8b949e">checked before a wave runs</text>
+<text x="700" y="22" font-weight="600" font-size="13.5" fill="#e6edf3">3. What cadence adds</text>
+<rect x="700" y="36" width="290" height="100" rx="6" fill="#0c2d6b" stroke="#58a6ff" stroke-width="2"/>
+<text x="845" y="76" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">Orchestrated wave</text>
+<text x="845" y="96" text-anchor="middle" font-size="11.5" fill="#c9d1d9">fresh sessions, review in the loop</text>
+<rect x="700" y="148" width="290" height="100" rx="6" fill="#0c2d6b" stroke="#58a6ff" stroke-width="2"/>
+<text x="845" y="188" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">Deliver</text>
+<text x="845" y="208" text-anchor="middle" font-size="11.5" fill="#c9d1d9">waits for CI, verifies the effect</text>
+<polyline points="310,145 358,145" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arw)"/>
+<polyline points="650,145 698,145" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arw)"/>
+</svg>

package/docs/with-your-tools-light.svg

@@ -0,0 +1,41 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1010 290" width="1010" height="290" role="img" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif" font-size="13" fill="#1f2328">
+<title>cadence next to the tools you already have</title>
+<desc>Your tools stay as they are: the tracker, HANDOFF.md, the ADRs and your commit convention. The plan can be read from your tracker's file, the plan commits follow your format and your docs are kept in step. On top, cadence adds orchestrated waves with an automatic review, and a deliver that verifies the effect.</desc>
+<defs><marker id="arw" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 z" fill="#57606a"/></marker></defs>
+<rect width="1010" height="290" fill="#ffffff"/>
+<text x="20" y="22" font-weight="600" font-size="13.5" fill="#1f2328">1. Your tools (kept)</text>
+<rect x="20" y="36" width="290" height="52" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="165" y="57" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">Linear, Jira</text>
+<text x="165" y="74" text-anchor="middle" font-size="11.5" fill="#57606a">tickets, board, assignment</text>
+<rect x="20" y="98" width="290" height="52" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="165" y="119" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">HANDOFF.md</text>
+<text x="165" y="136" text-anchor="middle" font-size="11.5" fill="#57606a">your hand-over notes</text>
+<rect x="20" y="160" width="290" height="52" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="165" y="181" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">ADRs</text>
+<text x="165" y="198" text-anchor="middle" font-size="11.5" fill="#57606a">your decisions</text>
+<rect x="20" y="222" width="290" height="52" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="165" y="243" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">Conventional Commits</text>
+<text x="165" y="260" text-anchor="middle" font-size="11.5" fill="#57606a">your commits</text>
+<text x="360" y="22" font-weight="600" font-size="13.5" fill="#1f2328">2. What plugs in</text>
+<rect x="360" y="36" width="290" height="52" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="505" y="57" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">plan: read-only</text>
+<text x="505" y="74" text-anchor="middle" font-size="11.5" fill="#57606a">your tracker export is the plan</text>
+<rect x="360" y="98" width="290" height="52" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="505" y="119" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">plan.commit</text>
+<text x="505" y="136" text-anchor="middle" font-size="11.5" fill="#57606a">plan commits in your format</text>
+<rect x="360" y="160" width="290" height="52" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="505" y="181" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">docs.sync</text>
+<text x="505" y="198" text-anchor="middle" font-size="11.5" fill="#57606a">your docs kept in step</text>
+<rect x="360" y="222" width="290" height="52" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="505" y="243" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">commit-msg hook</text>
+<text x="505" y="260" text-anchor="middle" font-size="11.5" fill="#57606a">checked before a wave runs</text>
+<text x="700" y="22" font-weight="600" font-size="13.5" fill="#1f2328">3. What cadence adds</text>
+<rect x="700" y="36" width="290" height="100" rx="6" fill="#ddf4ff" stroke="#0969da" stroke-width="2"/>
+<text x="845" y="76" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">Orchestrated wave</text>
+<text x="845" y="96" text-anchor="middle" font-size="11.5" fill="#57606a">fresh sessions, review in the loop</text>
+<rect x="700" y="148" width="290" height="100" rx="6" fill="#ddf4ff" stroke="#0969da" stroke-width="2"/>
+<text x="845" y="188" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">Deliver</text>
+<text x="845" y="208" text-anchor="middle" font-size="11.5" fill="#57606a">waits for CI, verifies the effect</text>
+<polyline points="310,145 358,145" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arw)"/>
+<polyline points="650,145 698,145" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arw)"/>
+</svg>

package/docs/with-your-tools.md

@@ -0,0 +1,95 @@
+[← cadence](../README.md)
+
+# cadence with your tools
+
+A team that already has a tracker (Linear, Jira), a `HANDOFF.md`, ADRs and a commit convention does not have to choose.
+cadence is a few plain files next to the code and a set of commands; each part is optional, and the parts that touch your habits bend to them.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="with-your-tools-dark.svg">
+  <img alt="Your tools stay: tracker, HANDOFF.md, ADRs, commit convention. The plan read from your tracker's file, the plan commits in your format and your docs kept in step plug in. cadence adds orchestrated waves with an automatic review, and a deliver that verifies the effect" src="with-your-tools-light.svg">
+</picture>
+
+## What cadence does not replace
+
+| You have | cadence does not | What it keeps out of |
+|---|---|---|
+| A tracker (Linear, Jira, GitHub issues) | no board, no assignment, no sprint, no comments, no notifications: its plan is a list of *lots* in a file | the tracker stays where the team agrees what to do and who does it |
+| `HANDOFF.md` | writes no hand-over document: `cadence session next "…"` keeps a one-line memo for the next `session start`, nothing more | keep your `HANDOFF.md`; cadence never reads or edits it |
+| ADRs | records no decision: a lot's notes are working notes (what was tried, what is left) | decisions that must last stay in your ADRs |
+| Conventional Commits (commitlint, husky) | does not impose a commit format: a commit belongs to a lot when it **cites the lot's id**, in the scope (`feat(ENG-12): …`) or anywhere in the message | your `commit-msg` hook keeps judging every commit, including the ones cadence writes (below) |
+
+## What is optional
+
+Nothing here needs the rest. Take one piece, leave the others:
+
+- **`raf`, the plan** (`raf init`, `raf add`, `raf start`, `raf done`): only if you want the plan in the repository. A plan kept by another tool is read as it is, never written (next section).
+- **`cadence session start` and `cadence session close`**: a morning and an evening report (lots in progress, commits without a lot, what is uncommitted or unpushed). Skip them if your stand-up or `HANDOFF.md` does that; they change nothing in the repository.
+- **`raf hook install`**: warns when a commit cites a lot that is not started. It never blocks a commit unless you set `hook.autostart` to say so.
+- **`cadence orchestrate` and `cadence deliver`**: a wave needs a plan it can read, a `raf` plan or a read-only one, and nothing else of the above; it works on a plan cadence never writes. `cadence deliver` is set by its own `deliver:` block and runs without a wave.
+
+## What plugs into what you have
+
+**A plan kept by another tool, read-only.** Point cadence at the file your tracker (or its export script) writes and map its keys. `raf list`, `raf now`, `raf commits`, `raf check`, `cadence session` and `cadence orchestrate` read it; `raf add|start|done|note` refuse and leave the write to your tool. The lot ids are yours (`ENG-12`), so your commits keep citing the ticket:
+
+```yaml
+# tracker/tickets.yaml
+tickets:
+  - key: ENG-12
+    summary: Export CSV
+    state: In Progress
+    points: 2
+    opened: 2026-10-20
+  - key: ENG-13
+    summary: Fix login redirect
+    state: Todo
+    points: 1
+    opened: 2026-10-21
+```
+
+```yaml
+# cadence.yaml, at the repository root
+plan:
+  path: tracker/tickets.yaml
+  lots: tickets                 # the root key holding the list
+  fields:                       # cadence's field: the key in your file
+    id: key
+    title: summary
+    status: state
+    estimate: points
+    created: opened
+  statuses:
+    todo: [Todo]
+    doing: [In Progress]
+    done: [Done]
+```
+
+All the keys (`add`, `files`, `ignore`, sub-tasks, `repos`…) are in [docs/raf.md](raf.md#a-plan-elsewhere-or-in-another-format).
+
+**The subject of the plan commits.** A wave commits the plan itself (the lot started, the review recorded). By default they still read `plan: L12 démarré (orchestrate …)`, which a commitlint `config-conventional` hook refuses: `plan` is not one of its types (GitHub issue #15). Set `plan.commit` in `cadence.yaml` to change the subject of all of them, and `cadence orchestrate --dry-run` runs each one through your real `commit-msg` hook before the wave starts:
+
+```yaml
+plan:
+  path: tracker/tickets.yaml
+  commit: 'chore({lot}): {action} (orchestrate {vague})'
+```
+
+`{lot}` is required, `{action}` and `{vague}` are optional; the full rules are in [docs/raf.md](raf.md#the-subject-of-the-plan-commits-plancommit-l343). The commits of the work itself are `type(<lot>): …` (`feat(ENG-12): …`), which is Conventional Commits already; a convention that wants something else is stated in the project's `CLAUDE.md`, which every session reads.
+
+**Your existing docs.** `docs.sync` tells cadence which of your documents must change when some code changes, and `raf check` reports a lot that left them behind. It adds no document of its own: the README, the `docs/` pages and the CHANGELOG you already have are the ones it watches.
+
+```yaml
+docs:
+  sync:
+    - paths: [src/**, '!**/*.test.ts']
+      docs: [README.md, docs/usage.md]
+```
+
+See [Documentation that follows the code](news.md#documentation-that-follows-the-code).
+
+## What it adds
+
+- **Orchestrated waves with an automatic review.** A lead picks the lots; each one goes to a fresh session that writes the tests first, commits and stops. A second, fresh session then reviews the commits against the lot and its notes before the lot can be closed. A red test suite or a missing document is sent back for correction, not found in the pull request. [docs/orchestrate.md](orchestrate.md), [docs/quickstart.md](quickstart.md).
+- **A deliver that verifies the effect.** `cadence deliver` waits for the CI of the pushed commit, runs your deploy commands, then replays the checks you declared (a URL that answers, a version that matches, a command that succeeds). A delivery is done when those checks pass, not when the pipeline says "success". [docs/deliver.md](deliver.md).
+
+Start small: a read-only plan and `plan.commit` are enough to see a wave run in a repository that keeps its tracker, its `HANDOFF.md`, its ADRs and its commit convention.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sylad/cadence",
-  "version": "1.15.1",
+  "version": "1.17.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",
@@ -47,6 +47,9 @@
     "docs/quickstart.md",
     "docs/quickstart-light.svg",
     "docs/quickstart-dark.svg",
+    "docs/with-your-tools.md",
+    "docs/with-your-tools-light.svg",
+    "docs/with-your-tools-dark.svg",
     "docs/cycle-vague-light.svg",
     "docs/cycle-vague-dark.svg",
     "LICENSE"