@sylad/cadence 1.6.0 → 1.8.0

package/docs/fonctionnement-lot-dark.svg

@@ -0,0 +1,38 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1100 190" width="1100" height="190" role="img" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif" font-size="13" fill="#e6edf3">
+<title>Life of a lot in the plan</title>
+<desc>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.</desc>
+<defs><marker id="arr1" 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="1100" height="190" fill="#0d1117"/>
+<rect x="20" y="40" width="110" height="56" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="75" y="64.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">todo</text>
+<text x="75" y="79.5" text-anchor="middle" font-size="11.5" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#8b949e">raf add</text>
+<rect x="230" y="40" width="130" height="56" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="295" y="64.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">doing</text>
+<text x="295" y="79.5" text-anchor="middle" font-size="11.5" fill="#8b949e">commits « Lx »</text>
+<rect x="470" y="40" width="170" height="56" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="555" y="64.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">Verdicts recorded</text>
+<text x="555" y="79.5" text-anchor="middle" font-size="11.5" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#8b949e">raf review · raf ux</text>
+<rect x="740" y="40" width="110" height="56" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="795" y="64.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">done</text>
+<text x="795" y="79.5" text-anchor="middle" font-size="11.5" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#8b949e">raf done</text>
+<rect x="950" y="40" width="130" height="56" rx="6" fill="#0c2d6b" stroke="#58a6ff" stroke-width="2"/>
+<text x="1015" y="64.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">Delivered</text>
+<text x="1015" y="79.5" text-anchor="middle" font-size="11.5" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#8b949e">cadence deliver</text>
+<polyline points="130,68 228,68" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr1)"/>
+<text x="180" y="60" text-anchor="middle" font-size="11.5" fill="#8b949e">raf start</text>
+<polyline points="360,68 468,68" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr1)"/>
+<text x="415" y="60" text-anchor="middle" font-size="11.5" fill="#8b949e">reviews</text>
+<polyline points="640,68 738,68" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr1)"/>
+<text x="690" y="60" text-anchor="middle" font-size="11.5" fill="#8b949e">gates passed</text>
+<polyline points="850,68 948,68" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr1)"/>
+<text x="900" y="60" text-anchor="middle" font-size="11.5" fill="#8b949e">push</text>
+<text x="75" y="124" text-anchor="middle" font-size="11.5" fill="#8b949e">raf drop → dropped</text>
+<text x="295" y="124" text-anchor="middle" font-size="11.5" fill="#8b949e">pre-commit: hook.autostart</text>
+<text x="295" y="140" text-anchor="middle" font-size="11.5" fill="#8b949e">warn · refuse · start</text>
+<text x="555" y="124" text-anchor="middle" font-size="11.5" fill="#8b949e">review: any lot with commits</text>
+<text x="555" y="140" text-anchor="middle" font-size="11.5" fill="#8b949e">ux: visible lot</text>
+<text x="795" y="124" text-anchor="middle" font-size="11.5" fill="#8b949e">refused with an open sub-task</text>
+<text x="1015" y="124" text-anchor="middle" font-size="11.5" fill="#8b949e">CI of the sha → deploy</text>
+<text x="1015" y="140" text-anchor="middle" font-size="11.5" fill="#8b949e">→ effect checks</text>
+<text x="1015" y="164" text-anchor="middle" font-size="11.5" fill="#8b949e">visible lot: news entry + capture</text>
+</svg>

package/docs/fonctionnement-lot-light.svg

@@ -0,0 +1,38 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1100 190" width="1100" height="190" role="img" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif" font-size="13" fill="#1f2328">
+<title>Life of a lot in the plan</title>
+<desc>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.</desc>
+<defs><marker id="arr1" 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="1100" height="190" fill="#ffffff"/>
+<rect x="20" y="40" width="110" height="56" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="75" y="64.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">todo</text>
+<text x="75" y="79.5" text-anchor="middle" font-size="11.5" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#57606a">raf add</text>
+<rect x="230" y="40" width="130" height="56" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="295" y="64.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">doing</text>
+<text x="295" y="79.5" text-anchor="middle" font-size="11.5" fill="#57606a">commits « Lx »</text>
+<rect x="470" y="40" width="170" height="56" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="555" y="64.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">Verdicts recorded</text>
+<text x="555" y="79.5" text-anchor="middle" font-size="11.5" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#57606a">raf review · raf ux</text>
+<rect x="740" y="40" width="110" height="56" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="795" y="64.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">done</text>
+<text x="795" y="79.5" text-anchor="middle" font-size="11.5" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#57606a">raf done</text>
+<rect x="950" y="40" width="130" height="56" rx="6" fill="#ddf4ff" stroke="#0969da" stroke-width="2"/>
+<text x="1015" y="64.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">Delivered</text>
+<text x="1015" y="79.5" text-anchor="middle" font-size="11.5" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#57606a">cadence deliver</text>
+<polyline points="130,68 228,68" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr1)"/>
+<text x="180" y="60" text-anchor="middle" font-size="11.5" fill="#57606a">raf start</text>
+<polyline points="360,68 468,68" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr1)"/>
+<text x="415" y="60" text-anchor="middle" font-size="11.5" fill="#57606a">reviews</text>
+<polyline points="640,68 738,68" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr1)"/>
+<text x="690" y="60" text-anchor="middle" font-size="11.5" fill="#57606a">gates passed</text>
+<polyline points="850,68 948,68" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr1)"/>
+<text x="900" y="60" text-anchor="middle" font-size="11.5" fill="#57606a">push</text>
+<text x="75" y="124" text-anchor="middle" font-size="11.5" fill="#57606a">raf drop → dropped</text>
+<text x="295" y="124" text-anchor="middle" font-size="11.5" fill="#57606a">pre-commit: hook.autostart</text>
+<text x="295" y="140" text-anchor="middle" font-size="11.5" fill="#57606a">warn · refuse · start</text>
+<text x="555" y="124" text-anchor="middle" font-size="11.5" fill="#57606a">review: any lot with commits</text>
+<text x="555" y="140" text-anchor="middle" font-size="11.5" fill="#57606a">ux: visible lot</text>
+<text x="795" y="124" text-anchor="middle" font-size="11.5" fill="#57606a">refused with an open sub-task</text>
+<text x="1015" y="124" text-anchor="middle" font-size="11.5" fill="#57606a">CI of the sha → deploy</text>
+<text x="1015" y="140" text-anchor="middle" font-size="11.5" fill="#57606a">→ effect checks</text>
+<text x="1015" y="164" text-anchor="middle" font-size="11.5" fill="#57606a">visible lot: news entry + capture</text>
+</svg>

package/docs/fonctionnement-service-dark.svg

@@ -0,0 +1,23 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1010 140" width="1010" height="140" role="img" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif" font-size="13" fill="#e6edf3">
+<title>Putting cadence itself in service</title>
+<desc>The cadence code on the PATH is a separate worktree, updated only by npm run service on a reviewed sha; a wave cannot put unreviewed code in service.</desc>
+<defs><marker id="arr4" 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="140" fill="#0d1117"/>
+<rect x="20" y="38" width="220" height="62" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="130" y="65.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">Working repository</text>
+<text x="130" y="80.5" text-anchor="middle" font-size="11.5" fill="#8b949e">waves, build = typecheck only</text>
+<rect x="320" y="38" width="260" height="62" rx="6" fill="#0c2d6b" stroke="#58a6ff" stroke-width="2"/>
+<text x="450" y="65.5" text-anchor="middle" font-size="11.5" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#8b949e">npm run service -- &lt;sha&gt;</text>
+<text x="450" y="80.5" text-anchor="middle" font-size="11.5" fill="#8b949e">ancestor of HEAD · cited lots done</text>
+<rect x="660" y="38" width="220" height="62" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="770" y="65.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">Service worktree</text>
+<text x="770" y="80.5" text-anchor="middle" font-size="11.5" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#8b949e">~/.local/share/cadence</text>
+<text x="945" y="74" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">PATH</text>
+<polyline points="240,69 318,69" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr4)"/>
+<text x="279" y="60" text-anchor="middle" font-size="11.5" fill="#8b949e">the lead,</text>
+<text x="279" y="92" text-anchor="middle" font-size="11.5" fill="#8b949e">after review</text>
+<polyline points="580,69 658,69" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr4)"/>
+<text x="619" y="60" text-anchor="middle" font-size="11.5" fill="#8b949e">build</text>
+<polyline points="880,69 918,69" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr4)"/>
+<text x="450" y="126" text-anchor="middle" font-size="11.5" fill="#8b949e">a dropped lot whose every commit is undone by a revert no longer blocks</text>
+</svg>

package/docs/fonctionnement-service-light.svg

@@ -0,0 +1,23 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1010 140" width="1010" height="140" role="img" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif" font-size="13" fill="#1f2328">
+<title>Putting cadence itself in service</title>
+<desc>The cadence code on the PATH is a separate worktree, updated only by npm run service on a reviewed sha; a wave cannot put unreviewed code in service.</desc>
+<defs><marker id="arr4" 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="140" fill="#ffffff"/>
+<rect x="20" y="38" width="220" height="62" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="130" y="65.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">Working repository</text>
+<text x="130" y="80.5" text-anchor="middle" font-size="11.5" fill="#57606a">waves, build = typecheck only</text>
+<rect x="320" y="38" width="260" height="62" rx="6" fill="#ddf4ff" stroke="#0969da" stroke-width="2"/>
+<text x="450" y="65.5" text-anchor="middle" font-size="11.5" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#57606a">npm run service -- &lt;sha&gt;</text>
+<text x="450" y="80.5" text-anchor="middle" font-size="11.5" fill="#57606a">ancestor of HEAD · cited lots done</text>
+<rect x="660" y="38" width="220" height="62" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="770" y="65.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">Service worktree</text>
+<text x="770" y="80.5" text-anchor="middle" font-size="11.5" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#57606a">~/.local/share/cadence</text>
+<text x="945" y="74" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">PATH</text>
+<polyline points="240,69 318,69" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr4)"/>
+<text x="279" y="60" text-anchor="middle" font-size="11.5" fill="#57606a">the lead,</text>
+<text x="279" y="92" text-anchor="middle" font-size="11.5" fill="#57606a">after review</text>
+<polyline points="580,69 658,69" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr4)"/>
+<text x="619" y="60" text-anchor="middle" font-size="11.5" fill="#57606a">build</text>
+<polyline points="880,69 918,69" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr4)"/>
+<text x="450" y="126" text-anchor="middle" font-size="11.5" fill="#57606a">a dropped lot whose every commit is undone by a revert no longer blocks</text>
+</svg>

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).