@sylad/cadence 1.6.0 → 1.7.0

package/docs/fonctionnement-wave-dark.svg

@@ -0,0 +1,66 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1320 350" width="1320" height="350" role="img" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif" font-size="13" fill="#e6edf3">
+<title>A lot inside an orchestrate wave</title>
+<desc>A lot without commits starts with a precheck (unless orchestrate.precheck is false), then by type through spec, mockup or sheet review and sealed acceptance tests, or straight to the implementation; then the code review, corrections (two passes, a third if the review converges), the UX pass if visible, once, after the compliant code review, and an automatic raf review.</desc>
+<defs><marker id="arr2" 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="1320" height="350" fill="#0d1117"/>
+<rect x="20" y="140" width="120" height="52" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5" stroke-dasharray="6 4"/>
+<text x="80" y="162.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">Precheck</text>
+<text x="80" y="177.5" text-anchor="middle" font-size="11.5" fill="#8b949e">local or Sonnet</text>
+<text x="80" y="212" text-anchor="middle" font-size="11.5" fill="#8b949e">already delivered?</text>
+<text x="80" y="227" text-anchor="middle" font-size="11.5" fill="#8b949e">yes → handed to the lead</text>
+<polyline points="140,166 165,166 165,60 198,60" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr2)"/>
+<polyline points="165,166 198,166" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr2)"/>
+<polyline points="165,166 165,272 728,272" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr2)"/>
+<text x="200" y="26" text-anchor="start" font-size="11.5" fill="#8b949e">screen: page only</text>
+<rect x="200" y="34" width="130" height="52" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="265" y="56.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">Spec</text>
+<text x="265" y="71.5" text-anchor="middle" font-size="11.5" fill="#8b949e">mockup + sheet</text>
+<rect x="360" y="34" width="150" height="52" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="435" y="56.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">Mockup review</text>
+<text x="435" y="71.5" text-anchor="middle" font-size="11.5" fill="#8b949e">ux-reviewer · ≤ 2</text>
+<polyline points="330,60 358,60" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr2)"/>
+<polyline points="510,60 558,60" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr2)"/>
+<text x="200" y="132" text-anchor="start" font-size="11.5" fill="#8b949e">spec: true</text>
+<rect x="200" y="140" width="130" height="52" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="265" y="162.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">Back-end spec</text>
+<text x="265" y="177.5" text-anchor="middle" font-size="11.5" fill="#8b949e">cases · rules · contracts</text>
+<rect x="360" y="140" width="150" height="52" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="435" y="162.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">Sheet review</text>
+<text x="435" y="177.5" text-anchor="middle" font-size="11.5" fill="#8b949e">code-reviewer · ≤ 2</text>
+<polyline points="330,166 358,166" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr2)"/>
+<polyline points="510,166 558,166" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr2)"/>
+<rect x="560" y="34" width="130" height="158" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5" stroke-dasharray="6 4"/>
+<text x="625" y="98" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">Accept</text>
+<text x="625" y="116" text-anchor="middle" font-size="11.5" fill="#8b949e">red tests</text>
+<text x="625" y="131" text-anchor="middle" font-size="11.5" fill="#8b949e">sealed</text>
+<text x="625" y="146" text-anchor="middle" font-size="11.5" fill="#8b949e">if orchestrate.accept</text>
+<polyline points="690,166 728,166" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr2)"/>
+<text x="200" y="262" text-anchor="start" font-size="11.5" fill="#8b949e">any other lot, component and journey included, unless it already has a sheet</text>
+<rect x="730" y="140" width="130" height="158" rx="6" fill="#0c2d6b" stroke="#58a6ff" stroke-width="2"/>
+<text x="795" y="208" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">Implementation</text>
+<text x="795" y="223" text-anchor="middle" font-size="11.5" fill="#8b949e">test first</text>
+<text x="795" y="238" text-anchor="middle" font-size="11.5" fill="#8b949e">commits citing the lot</text>
+<rect x="888" y="193" width="140" height="52" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="958" y="215.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">Code review</text>
+<text x="958" y="230.5" text-anchor="middle" font-size="11.5" fill="#8b949e">Opus, Sonnet if ≤ 0.25 d</text>
+<polyline points="860,219 886,219" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr2)"/>
+<rect x="1050" y="193" width="140" height="52" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5" stroke-dasharray="6 4"/>
+<text x="1120" y="215.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">UX pass</text>
+<text x="1120" y="230.5" text-anchor="middle" font-size="11.5" fill="#8b949e">visible lot · once, last</text>
+<polyline points="1028,219 1048,219" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr2)"/>
+<rect x="1050" y="286" width="140" height="48" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="1120" y="306.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">Correction</text>
+<text x="1120" y="321.5" text-anchor="middle" font-size="11.5" fill="#8b949e">fresh session</text>
+<polyline points="1100,245 1100,284" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr2)"/>
+<text x="1094" y="270" text-anchor="end" font-size="11.5" fill="#8b949e">not compliant</text>
+<polyline points="1140,286 1140,247" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr2)"/>
+<text x="1147" y="262" text-anchor="start" font-size="11.5" fill="#8b949e">≤ 2 passes,</text>
+<text x="1147" y="277" text-anchor="start" font-size="11.5" fill="#8b949e">3rd if it converges</text>
+<rect x="1230" y="193" width="80" height="52" rx="6" fill="#0c2d6b" stroke="#58a6ff" stroke-width="2"/>
+<text x="1270" y="215.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">raf review</text>
+<text x="1270" y="230.5" text-anchor="middle" font-size="11.5" fill="#8b949e">recorded</text>
+<polyline points="1190,219 1228,219" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr2)"/>
+<text x="900" y="162" text-anchor="start" font-size="11.5" fill="#8b949e">small lot: one pass,</text>
+<text x="900" y="177" text-anchor="start" font-size="11.5" fill="#8b949e">review-small if visible</text>
+<text x="1210" y="186" text-anchor="middle" font-size="11.5" fill="#8b949e">compliant</text>
+</svg>

package/docs/fonctionnement-wave-light.svg

@@ -0,0 +1,66 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1320 350" width="1320" height="350" role="img" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif" font-size="13" fill="#1f2328">
+<title>A lot inside an orchestrate wave</title>
+<desc>A lot without commits starts with a precheck (unless orchestrate.precheck is false), then by type through spec, mockup or sheet review and sealed acceptance tests, or straight to the implementation; then the code review, corrections (two passes, a third if the review converges), the UX pass if visible, once, after the compliant code review, and an automatic raf review.</desc>
+<defs><marker id="arr2" 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="1320" height="350" fill="#ffffff"/>
+<rect x="20" y="140" width="120" height="52" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5" stroke-dasharray="6 4"/>
+<text x="80" y="162.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">Precheck</text>
+<text x="80" y="177.5" text-anchor="middle" font-size="11.5" fill="#57606a">local or Sonnet</text>
+<text x="80" y="212" text-anchor="middle" font-size="11.5" fill="#57606a">already delivered?</text>
+<text x="80" y="227" text-anchor="middle" font-size="11.5" fill="#57606a">yes → handed to the lead</text>
+<polyline points="140,166 165,166 165,60 198,60" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr2)"/>
+<polyline points="165,166 198,166" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr2)"/>
+<polyline points="165,166 165,272 728,272" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr2)"/>
+<text x="200" y="26" text-anchor="start" font-size="11.5" fill="#57606a">screen: page only</text>
+<rect x="200" y="34" width="130" height="52" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="265" y="56.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">Spec</text>
+<text x="265" y="71.5" text-anchor="middle" font-size="11.5" fill="#57606a">mockup + sheet</text>
+<rect x="360" y="34" width="150" height="52" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="435" y="56.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">Mockup review</text>
+<text x="435" y="71.5" text-anchor="middle" font-size="11.5" fill="#57606a">ux-reviewer · ≤ 2</text>
+<polyline points="330,60 358,60" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr2)"/>
+<polyline points="510,60 558,60" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr2)"/>
+<text x="200" y="132" text-anchor="start" font-size="11.5" fill="#57606a">spec: true</text>
+<rect x="200" y="140" width="130" height="52" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="265" y="162.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">Back-end spec</text>
+<text x="265" y="177.5" text-anchor="middle" font-size="11.5" fill="#57606a">cases · rules · contracts</text>
+<rect x="360" y="140" width="150" height="52" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="435" y="162.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">Sheet review</text>
+<text x="435" y="177.5" text-anchor="middle" font-size="11.5" fill="#57606a">code-reviewer · ≤ 2</text>
+<polyline points="330,166 358,166" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr2)"/>
+<polyline points="510,166 558,166" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr2)"/>
+<rect x="560" y="34" width="130" height="158" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5" stroke-dasharray="6 4"/>
+<text x="625" y="98" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">Accept</text>
+<text x="625" y="116" text-anchor="middle" font-size="11.5" fill="#57606a">red tests</text>
+<text x="625" y="131" text-anchor="middle" font-size="11.5" fill="#57606a">sealed</text>
+<text x="625" y="146" text-anchor="middle" font-size="11.5" fill="#57606a">if orchestrate.accept</text>
+<polyline points="690,166 728,166" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr2)"/>
+<text x="200" y="262" text-anchor="start" font-size="11.5" fill="#57606a">any other lot, component and journey included, unless it already has a sheet</text>
+<rect x="730" y="140" width="130" height="158" rx="6" fill="#ddf4ff" stroke="#0969da" stroke-width="2"/>
+<text x="795" y="208" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">Implementation</text>
+<text x="795" y="223" text-anchor="middle" font-size="11.5" fill="#57606a">test first</text>
+<text x="795" y="238" text-anchor="middle" font-size="11.5" fill="#57606a">commits citing the lot</text>
+<rect x="888" y="193" width="140" height="52" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="958" y="215.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">Code review</text>
+<text x="958" y="230.5" text-anchor="middle" font-size="11.5" fill="#57606a">Opus, Sonnet if ≤ 0.25 d</text>
+<polyline points="860,219 886,219" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr2)"/>
+<rect x="1050" y="193" width="140" height="52" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5" stroke-dasharray="6 4"/>
+<text x="1120" y="215.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">UX pass</text>
+<text x="1120" y="230.5" text-anchor="middle" font-size="11.5" fill="#57606a">visible lot · once, last</text>
+<polyline points="1028,219 1048,219" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr2)"/>
+<rect x="1050" y="286" width="140" height="48" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="1120" y="306.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">Correction</text>
+<text x="1120" y="321.5" text-anchor="middle" font-size="11.5" fill="#57606a">fresh session</text>
+<polyline points="1100,245 1100,284" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr2)"/>
+<text x="1094" y="270" text-anchor="end" font-size="11.5" fill="#57606a">not compliant</text>
+<polyline points="1140,286 1140,247" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr2)"/>
+<text x="1147" y="262" text-anchor="start" font-size="11.5" fill="#57606a">≤ 2 passes,</text>
+<text x="1147" y="277" text-anchor="start" font-size="11.5" fill="#57606a">3rd if it converges</text>
+<rect x="1230" y="193" width="80" height="52" rx="6" fill="#ddf4ff" stroke="#0969da" stroke-width="2"/>
+<text x="1270" y="215.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">raf review</text>
+<text x="1270" y="230.5" text-anchor="middle" font-size="11.5" fill="#57606a">recorded</text>
+<polyline points="1190,219 1228,219" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr2)"/>
+<text x="900" y="162" text-anchor="start" font-size="11.5" fill="#57606a">small lot: one pass,</text>
+<text x="900" y="177" text-anchor="start" font-size="11.5" fill="#57606a">review-small if visible</text>
+<text x="1210" y="186" text-anchor="middle" font-size="11.5" fill="#57606a">compliant</text>
+</svg>

package/docs/fonctionnement.md

@@ -0,0 +1,106 @@
+# How cadence works
+
+A versioned plan (`raf`) tied to the commits, waves of fresh sessions driven by a program
+(`cadence orchestrate`), a lead that decides and re-verifies, then deliveries proved by their effect.
+Four figures go from the isolated lot to the tool itself. Dashed boxes are conditional steps; a
+box with a blue outline is where the work is kept or checked.
+
+## 1. The life of a lot in the plan
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="fonctionnement-lot-dark.svg">
+  <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:
+`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
+while a sub-task is open. A delivery is finished only when its effect checks pass.
+
+## 2. A lot inside a wave
+
+<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">
+</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
+to the lead; « partial » passes what exists to the implementation. Then:
+
+- `screen: page` only: **spec** (mockup and screen sheet), **mockup review** (`ux-reviewer`, two
+  passes at most), then **accept**. `screen: component` and `screen: journey` lots take the ordinary
+  path, unless their sheet already exists.
+- `spec: true` (a lot with a behaviour to pin down and no screen): **back-end spec** (cases, rules,
+  contracts), **sheet review** (`code-reviewer` in sheet mode, two passes at most), then **accept**.
+  A mixed lot (a page whose sheet has a `sujet` block) gets both reviews and a single second spec pass.
+- **accept** writes the acceptance tests from the sheet, committed red and locked, when the project
+  declares `orchestrate.accept`.
+- every other lot goes straight to the **implementation**: test first, commits that cite the lot.
+
+After the implementation: the **code review** (Opus, Sonnet for a lot of 0.25 day or less); a
+**correction** in a fresh session if the review is not compliant, two passes at most, and a third
+only when the review converges (the count of blocking + major findings dropped and only one is
+left), each followed by a review. A compliant review makes the program record `raf review` itself;
+for a `visible` lot whose project says how to see its app (`orchestrate.ux`), the **UX pass** comes
+once, after the compliant code review (a blocking or major UX finding sends the lot to a correction,
+then the code review, then the UX pass again).
+A small lot (estimate of 0.5 day or less, or `quickwin`) has a single review pass, with no separate UX pass:
+`review-small` covering code and usability when the lot is `visible`, a code `review` otherwise.
+
+## 3. The lead drives the waves
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="fonctionnement-lead-dark.svg">
+  <img alt="Three lanes: the human chooses and decides, the lead starts, relays, re-verifies and delivers, the orchestrate program runs the lots and chains the next wave while the context stays under 60 percent" src="fonctionnement-lead-light.svg">
+</picture>
+
+The lead does not code and never commits where a wave runs. It re-verifies itself (git log, tests,
+build, `raf check`) before `raf done`, delivers one project at a time, and never pushes above a
+handed-back lot (only « livrable jusqu'à `<sha>` »). The UX verdict is the human's, or the lead's
+when the parent folder's `cadence.yaml` says `lead.ux: lead`; the human is then asked only at the
+slightest doubt. The step-by-step version, with its three lanes, is in [lead.md](lead.md).
+
+## 4. Putting cadence itself in service
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="fonctionnement-service-dark.svg">
+  <img alt="The cadence code on the PATH is a separate worktree, updated only by npm run service on a reviewed sha" src="fonctionnement-service-light.svg">
+</picture>
+
+On the cadence repository itself, the `raf` and `cadence` commands of the `PATH` do not read the
+working repository's `dist/`: they read a separate worktree under `~/.local/share/cadence`, updated
+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.
+
+## Budget of a lot
+
+The budget a wave gives a lot is derived from its estimate, measured on the runs of the project:
+
+| Lot | Budget |
+|---|---|
+| up to 0.5 day | 540 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 |
+| `spec: true` | ordinary budget + 450 k |
+| fix pass and short review | 155 k reserved |
+
+The final review is always played; the budget bounds the writing passes. A `screen: component` or
+`screen: journey` lot takes the ordinary budget, unless its sheet already exists: it then gets the
+`screen: page` budget.
+
+## Permanent rules
+
+- **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.
+- 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`.
+- Deliveries and the `raf ux` / `raf review` verdicts belong to the lead, one project at a time.
+
+See also the [orchestrate](orchestrate.md#orchestrate) page and the
+[lead tour](lead.md#lead-tour).

package/docs/lead-workflow-dark.svg

@@ -0,0 +1,200 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1650 810" width="1650" height="810" role="img" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif" font-size="13" fill="#e6edf3">
+<title>Workflow of the lead skill in three lanes: the human, the lead session, and the orchestrate program with its agents</title>
+<defs><marker id="arr" 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>
+<marker id="arrw" 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="#ff7b72"/></marker></defs>
+<rect width="1650" height="810" fill="#0d1117"/>
+<text x="825" y="34" text-anchor="middle" font-size="18" font-weight="600">The lead workflow: decide at the top, work in fresh sessions</text>
+<rect x="10" y="70" width="1630" height="200" fill="#161b22" stroke="#30363d"/>
+<line x1="150" y1="70" x2="150" y2="270" stroke="#30363d"/>
+<text x="24" y="146" font-weight="700" font-size="15" fill="#d29922">Human</text>
+<text x="24" y="166" font-size="11.5" fill="#8b949e">chooses, answers,</text>
+<text x="24" y="181" font-size="11.5" fill="#8b949e">gives the UX verdict</text>
+<rect x="10" y="270" width="1630" height="200" fill="#0d1117" stroke="#30363d"/>
+<line x1="150" y1="270" x2="150" y2="470" stroke="#30363d"/>
+<text x="24" y="339" font-weight="700" font-size="15" fill="#58a6ff">Lead session</text>
+<text x="24" y="359" font-size="11.5" fill="#8b949e">stays small:</text>
+<text x="24" y="374" font-size="11.5" fill="#8b949e">reads, decides, checks,</text>
+<text x="24" y="389" font-size="11.5" fill="#8b949e">delivers</text>
+<rect x="10" y="470" width="1630" height="320" fill="#161b22" stroke="#30363d"/>
+<line x1="150" y1="470" x2="150" y2="790" stroke="#30363d"/>
+<text x="24" y="606" font-weight="700" font-size="15" fill="#3fb950">orchestrate</text>
+<text x="24" y="626" font-size="11.5" fill="#8b949e">program and agents</text>
+<text x="24" y="641" font-size="11.5" fill="#8b949e">(fresh short sessions)</text>
+<text x="240" y="88" text-anchor="middle" font-size="11.5" font-weight="600" fill="#8b949e">1 Tour</text>
+<text x="420" y="88" text-anchor="middle" font-size="11.5" font-weight="600" fill="#8b949e">2 Wave</text>
+<text x="600" y="88" text-anchor="middle" font-size="11.5" font-weight="600" fill="#8b949e">3 Relay</text>
+<text x="780" y="88" text-anchor="middle" font-size="11.5" font-weight="600" fill="#8b949e">4 Review</text>
+<text x="960" y="88" text-anchor="middle" font-size="11.5" font-weight="600" fill="#8b949e">5 Re-check</text>
+<text x="1140" y="88" text-anchor="middle" font-size="11.5" font-weight="600" fill="#8b949e">6 Delivery</text>
+<text x="1320" y="88" text-anchor="middle" font-size="11.5" font-weight="600" fill="#8b949e">7 Threshold</text>
+<text x="1500" y="88" text-anchor="middle" font-size="11.5" font-weight="600" fill="#8b949e">8 Close</text>
+<g id="tour"><rect x="161" y="337" width="158" height="66" rx="8" fill="#0c2d6b" stroke="#58a6ff" stroke-width="1.5"/>
+<text x="240" y="358.5" text-anchor="middle" font-weight="600" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" font-size="11.5">cadence lead tour</text>
+<text x="240" y="374.5" text-anchor="middle">one line per project</text>
+<text x="240" y="390.5" text-anchor="middle">+ three proposals</text>
+</g>
+<g id="choose"><rect x="161" y="137" width="158" height="66" rx="8" fill="#3d2e00" stroke="#d29922" stroke-width="1.5"/>
+<text x="240" y="158.5" text-anchor="middle" font-weight="600">Picks the lots</text>
+<text x="240" y="174.5" text-anchor="middle">and the order</text>
+<text x="240" y="190.5" text-anchor="middle">(the priority)</text>
+</g>
+<g id="launch"><rect x="341" y="337" width="158" height="66" rx="8" fill="#0c2d6b" stroke="#58a6ff" stroke-width="1.5"/>
+<text x="420" y="358.5" text-anchor="middle" font-weight="600">Starts the wave</text>
+<text x="420" y="374.5" text-anchor="middle" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" font-size="11.5">orchestrate … --wave</text>
+<text x="420" y="390.5" text-anchor="middle">in the background</text>
+</g>
+<g id="precheck"><rect x="161" y="508" width="158" height="82" rx="8" fill="#0f2d1a" stroke="#3fb950" stroke-width="1.5" stroke-dasharray="5 3"/>
+<text x="240" y="529.5" text-anchor="middle" font-weight="600">Precheck</text>
+<text x="240" y="545.5" text-anchor="middle">local model or Sonnet:</text>
+<text x="240" y="561.5" text-anchor="middle">already delivered?</text>
+<text x="240" y="577.5" text-anchor="middle">yes → back to lead</text>
+</g>
+<g id="spec"><rect x="341" y="480" width="158" height="66" rx="8" fill="#0f2d1a" stroke="#3fb950" stroke-width="1.5" stroke-dasharray="5 3"/>
+<text x="420" y="501.5" text-anchor="middle" font-weight="600">Spec (screen: page)</text>
+<text x="420" y="517.5" text-anchor="middle">spec-writer: mockup</text>
+<text x="420" y="533.5" text-anchor="middle">+ sheet, 1440 / 390</text>
+</g>
+<g id="mockup"><rect x="521" y="480" width="158" height="66" rx="8" fill="#0f2d1a" stroke="#3fb950" stroke-width="1.5" stroke-dasharray="5 3"/>
+<text x="600" y="501.5" text-anchor="middle" font-weight="600">Mockup review</text>
+<text x="600" y="517.5" text-anchor="middle">ux-reviewer, 2 passes</text>
+<text x="600" y="533.5" text-anchor="middle">max, then handed back</text>
+</g>
+<g id="backspec"><rect x="341" y="552" width="158" height="66" rx="8" fill="#0f2d1a" stroke="#3fb950" stroke-width="1.5" stroke-dasharray="5 3"/>
+<text x="420" y="573.5" text-anchor="middle" font-weight="600">Back-end spec</text>
+<text x="420" y="589.5" text-anchor="middle">spec: true: cases,</text>
+<text x="420" y="605.5" text-anchor="middle">rules, contracts</text>
+</g>
+<g id="sheetreview"><rect x="521" y="552" width="158" height="66" rx="8" fill="#0f2d1a" stroke="#3fb950" stroke-width="1.5" stroke-dasharray="5 3"/>
+<text x="600" y="573.5" text-anchor="middle" font-weight="600">Sheet review</text>
+<text x="600" y="589.5" text-anchor="middle">code-reviewer, 2</text>
+<text x="600" y="605.5" text-anchor="middle">passes max</text>
+</g>
+<g id="accept"><rect x="701" y="480" width="158" height="138" rx="8" fill="#0f2d1a" stroke="#3fb950" stroke-width="1.5" stroke-dasharray="5 3"/>
+<text x="780" y="543" text-anchor="middle" font-weight="600">Accept</text>
+<text x="780" y="559" text-anchor="middle">red tests + lock</text>
+<text x="780" y="575" text-anchor="middle">if accept declared</text>
+</g>
+<g id="implement"><rect x="341" y="650" width="158" height="66" rx="8" fill="#0f2d1a" stroke="#3fb950" stroke-width="1.5"/>
+<text x="420" y="671.5" text-anchor="middle" font-weight="600">Implementation</text>
+<text x="420" y="687.5" text-anchor="middle">test first, commits</text>
+<text x="420" y="703.5" text-anchor="middle">cite the lot</text>
+</g>
+<g id="relay"><rect x="521" y="337" width="158" height="66" rx="8" fill="#0c2d6b" stroke="#58a6ff" stroke-width="1.5"/>
+<text x="600" y="358.5" text-anchor="middle" font-weight="600">Relays the journal</text>
+<text x="600" y="374.5" text-anchor="middle" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" font-size="11.5">tail -F journal.log</text>
+<text x="600" y="390.5" text-anchor="middle">one sentence per line</text>
+</g>
+<g id="answer"><rect x="521" y="137" width="158" height="66" rx="8" fill="#3d2e00" stroke="#d29922" stroke-width="1.5"/>
+<text x="600" y="158.5" text-anchor="middle" font-weight="600">Answers a question</text>
+<text x="600" y="174.5" text-anchor="middle">the lead never</text>
+<text x="600" y="190.5" text-anchor="middle">answers for them</text>
+</g>
+<g id="uxpass"><rect x="521" y="650" width="158" height="66" rx="8" fill="#0f2d1a" stroke="#3fb950" stroke-width="1.5" stroke-dasharray="5 3"/>
+<text x="600" y="671.5" text-anchor="middle" font-weight="600">UX pass</text>
+<text x="600" y="687.5" text-anchor="middle">visible lot + app</text>
+<text x="600" y="703.5" text-anchor="middle">declared; vs mockup</text>
+</g>
+<g id="codereview"><rect x="701" y="650" width="158" height="66" rx="8" fill="#0f2d1a" stroke="#3fb950" stroke-width="1.5"/>
+<text x="780" y="671.5" text-anchor="middle" font-weight="600">Code review</text>
+<text x="780" y="687.5" text-anchor="middle">Opus (Sonnet ≤ 0.25 d)</text>
+<text x="780" y="703.5" text-anchor="middle">records raf review</text>
+</g>
+<g id="fix"><rect x="881" y="650" width="158" height="66" rx="8" fill="#0f2d1a" stroke="#3fb950" stroke-width="1.5" stroke-dasharray="5 3"/>
+<text x="960" y="671.5" text-anchor="middle" font-weight="600">Correction</text>
+<text x="960" y="687.5" text-anchor="middle">new session, 2 passes</text>
+<text x="960" y="703.5" text-anchor="middle">3rd if it converges</text>
+</g>
+<g id="table"><rect x="701" y="337" width="158" height="66" rx="8" fill="#0c2d6b" stroke="#58a6ff" stroke-width="1.5"/>
+<text x="780" y="358.5" text-anchor="middle" font-weight="600">Final table</text>
+<text x="780" y="374.5" text-anchor="middle">ready · handed back</text>
+<text x="780" y="390.5" text-anchor="middle">· « livrable jusqu'à »</text>
+</g>
+<g id="recheck"><rect x="881" y="337" width="158" height="66" rx="8" fill="#0c2d6b" stroke="#58a6ff" stroke-width="1.5"/>
+<text x="960" y="358.5" text-anchor="middle" font-weight="600">Re-verifies itself</text>
+<text x="960" y="374.5" text-anchor="middle">git log · tests · build</text>
+<text x="960" y="390.5" text-anchor="middle" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" font-size="11.5">raf check</text>
+</g>
+<g id="uxverdict"><rect x="881" y="137" width="158" height="66" rx="8" fill="#3d2e00" stroke="#d29922" stroke-width="1.5"/>
+<text x="960" y="158.5" text-anchor="middle" font-weight="600">Looks at the captures</text>
+<text x="960" y="174.5" text-anchor="middle">UX verdict →</text>
+<text x="960" y="190.5" text-anchor="middle" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" font-size="11.5">raf ux (visible lot)</text>
+</g>
+<g id="done"><rect x="1061" y="337" width="158" height="66" rx="8" fill="#0c2d6b" stroke="#58a6ff" stroke-width="1.5"/>
+<text x="1140" y="358.5" text-anchor="middle" font-weight="600" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" font-size="11.5">raf done</text>
+<text x="1140" y="374.5" text-anchor="middle">then push</text>
+<text x="1140" y="390.5" text-anchor="middle" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" font-size="11.5">cadence deliver</text>
+</g>
+<g id="qa"><rect x="1061" y="650" width="158" height="66" rx="8" fill="#0f2d1a" stroke="#3fb950" stroke-width="1.5" stroke-dasharray="5 3"/>
+<text x="1140" y="671.5" text-anchor="middle" font-weight="600">qa-reviewer</text>
+<text x="1140" y="687.5" text-anchor="middle">reads only; blocking</text>
+<text x="1140" y="703.5" text-anchor="middle">findings → the human</text>
+</g>
+<g id="ctx"><rect x="1241" y="337" width="158" height="66" rx="8" fill="#0c2d6b" stroke="#58a6ff" stroke-width="1.5"/>
+<text x="1320" y="358.5" text-anchor="middle" font-weight="600">Context under 60 %?</text>
+<text x="1320" y="374.5" text-anchor="middle" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" font-size="11.5">session context</text>
+<text x="1320" y="390.5" text-anchor="middle">error = at threshold</text>
+</g>
+<g id="next"><rect x="1241" y="650" width="158" height="66" rx="8" fill="#0f2d1a" stroke="#3fb950" stroke-width="1.5"/>
+<text x="1320" y="671.5" text-anchor="middle" font-weight="600">Next wave</text>
+<text x="1320" y="687.5" text-anchor="middle" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" font-size="11.5">… --continue</text>
+<text x="1320" y="703.5" text-anchor="middle">draws the next ready lot</text>
+</g>
+<g id="close"><rect x="1421" y="337" width="158" height="66" rx="8" fill="#0c2d6b" stroke="#58a6ff" stroke-width="1.5"/>
+<text x="1500" y="358.5" text-anchor="middle" font-weight="600">Close</text>
+<text x="1500" y="374.5" text-anchor="middle" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" font-size="11.5">session-close</text>
+<text x="1500" y="390.5" text-anchor="middle" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" font-size="11.5">session next ×3</text>
+</g>
+<g id="report"><rect x="1421" y="137" width="158" height="66" rx="8" fill="#3d2e00" stroke="#d29922" stroke-width="1.5"/>
+<text x="1500" y="158.5" text-anchor="middle" font-weight="600">One line per project</text>
+<text x="1500" y="174.5" text-anchor="middle">delivered · in progress</text>
+<text x="1500" y="190.5" text-anchor="middle">· blocked (and why)</text>
+</g>
+<polyline points="240,337 240,203" fill="none" stroke="#8b949e" stroke-width="1.6" marker-end="url(#arr)"/>
+<text x="248" y="236" text-anchor="start" font-size="11" fill="#8b949e" class="lbl">proposals</text>
+<polyline points="319,170 420,170 420,337" fill="none" stroke="#8b949e" stroke-width="1.6" marker-end="url(#arr)"/>
+<text x="414" y="164" text-anchor="end" font-size="11" fill="#8b949e" class="lbl">choice</text>
+<polyline points="499,683 521,683" fill="none" stroke="#8b949e" stroke-width="1.6" marker-end="url(#arr)"/>
+<polyline points="679,683 701,683" fill="none" stroke="#8b949e" stroke-width="1.6" marker-end="url(#arr)"/>
+<polyline points="859,683 881,683" fill="none" stroke="#8b949e" stroke-width="1.6" marker-end="url(#arr)"/>
+<polyline points="960,650 960,632 820,632 820,650" fill="none" stroke="#8b949e" stroke-width="1.6" marker-end="url(#arr)"/>
+<text x="968" y="626" text-anchor="start" font-size="11" fill="#8b949e" class="lbl">then review again</text>
+<polyline points="870,683 870,430 780,430 780,403" fill="none" stroke="#8b949e" stroke-width="1.6" marker-end="url(#arr)"/>
+<text x="876" y="446" text-anchor="start" font-size="11" fill="#8b949e" class="lbl">wave ends</text>
+<polyline points="510,683 510,430 600,430 600,403" fill="none" stroke="#8b949e" stroke-width="1.6" marker-end="url(#arr)"/>
+<text x="516" y="646" text-anchor="start" font-size="11" fill="#8b949e" class="lbl">journal</text>
+<polyline points="630,337 630,203" fill="none" stroke="#8b949e" stroke-width="1.6" marker-end="url(#arr)"/>
+<text x="636" y="236" text-anchor="start" font-size="11" fill="#8b949e" class="lbl">question</text>
+<polyline points="570,203 570,337" fill="none" stroke="#8b949e" stroke-width="1.6" marker-end="url(#arr)"/>
+<text x="564" y="236" text-anchor="end" font-size="11" class="lbl" fill="#8b949e">--resume --answer</text>
+<polyline points="859,370 881,370" fill="none" stroke="#8b949e" stroke-width="1.6" marker-end="url(#arr)"/>
+<polyline points="960,203 960,337" fill="none" stroke="#8b949e" stroke-width="1.6" marker-end="url(#arr)"/>
+<text x="968" y="236" text-anchor="start" font-size="11" fill="#8b949e" class="lbl">on the human's verdict,</text>
+<text x="968" y="251" text-anchor="start" font-size="11" fill="#8b949e" class="lbl">or the lead's (lead.ux: lead)</text>
+<polyline points="1039,370 1061,370" fill="none" stroke="#8b949e" stroke-width="1.6" marker-end="url(#arr)"/>
+<polyline points="1140,403 1140,650" fill="none" stroke="#8b949e" stroke-width="1.6" marker-end="url(#arr)"/>
+<polyline points="1320,403 1320,650" fill="none" stroke="#8b949e" stroke-width="1.6" marker-end="url(#arr)"/>
+<text x="1326" y="440" text-anchor="start" font-size="11" fill="#8b949e" class="lbl">yes: chain</text>
+<polyline points="1399,370 1421,370" fill="none" stroke="#8b949e" stroke-width="1.6" marker-end="url(#arr)"/>
+<text x="1410" y="329" text-anchor="middle" font-size="11" fill="#8b949e" class="lbl">≥ 60 %: close</text>
+<polyline points="1500,337 1500,203" fill="none" stroke="#8b949e" stroke-width="1.6" marker-end="url(#arr)"/>
+<polyline points="1320,716 1320,746 420,746 420,716" fill="none" stroke="#8b949e" stroke-width="1.6" marker-end="url(#arr)"/>
+<text x="870" y="740" text-anchor="middle" font-size="11" fill="#8b949e" class="lbl">next wave: back to step 2, the limits still apply</text>
+<rect x="170" y="760" width="22" height="14" rx="3" fill="none" stroke="#8b949e" stroke-dasharray="5 3"/>
+<text x="200" y="771" font-size="11.5" fill="#8b949e">conditional step</text>
+<text x="340" y="771" font-size="11.5" fill="#8b949e">The lead never commits where a wave runs, and never delivers two projects at once. At most as many sessions or subagents as the cap the human sets (CADENCE_MAX_SESSIONS, 2 by default).</text>
+<polyline points="420,403 420,440 240,440 240,508" fill="none" stroke="#8b949e" stroke-width="1.6" marker-end="url(#arr)"/>
+<polyline points="319,549 330,549 330,513 341,513" fill="none" stroke="#8b949e" stroke-width="1.6" marker-end="url(#arr)"/>
+<polyline points="330,549 330,585 341,585" fill="none" stroke="#8b949e" stroke-width="1.6" marker-end="url(#arr)"/>
+<polyline points="499,513 521,513" fill="none" stroke="#8b949e" stroke-width="1.6" marker-end="url(#arr)"/>
+<polyline points="679,513 701,513" fill="none" stroke="#8b949e" stroke-width="1.6" marker-end="url(#arr)"/>
+<polyline points="499,585 521,585" fill="none" stroke="#8b949e" stroke-width="1.6" marker-end="url(#arr)"/>
+<polyline points="679,585 701,585" fill="none" stroke="#8b949e" stroke-width="1.6" marker-end="url(#arr)"/>
+<polyline points="240,590 240,683 341,683" fill="none" stroke="#8b949e" stroke-width="1.6" marker-end="url(#arr)"/>
+<polyline points="780,618 780,634 420,634 420,650" fill="none" stroke="#8b949e" stroke-width="1.6" marker-end="url(#arr)"/>
+<text x="232" y="640" text-anchor="end" font-size="11" fill="#8b949e" class="lbl">other lots</text>
+<text x="232" y="655" text-anchor="end" font-size="11" fill="#8b949e" class="lbl">go straight on</text>
+<text x="890" y="508" text-anchor="start" font-size="11" fill="#8b949e" class="lbl">lots with screen: page</text>
+<text x="890" y="523" text-anchor="start" font-size="11" fill="#8b949e" class="lbl">spec, mockup, accept</text>
+<text x="890" y="568" text-anchor="start" font-size="11" fill="#8b949e" class="lbl">lots with spec: true</text>
+<text x="890" y="583" text-anchor="start" font-size="11" fill="#8b949e" class="lbl">spec, sheet review, accept</text>
+</svg>