@sylad/cadence 1.39.0 → 1.40.0

package/docs/concepts-lot-light.svg

@@ -0,0 +1,52 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1100 300" width="1100" height="300" role="img" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif" font-size="13" fill="#1f2328">
+<title>Journey of a lot</title>
+<desc>A lot goes through spec, code, review, correction when the review is not compliant, UX if the lot is visible, then ready; below each step, who does it.</desc>
+<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="#57606a"/></marker></defs>
+<rect width="1100" height="300" fill="#ffffff"/>
+<text x="20" y="26" text-anchor="start" font-size="11.5" font-weight="600" fill="#57606a">STEP</text>
+<text x="20" y="168" text-anchor="start" font-size="11.5" font-weight="600" fill="#57606a">WHO</text>
+<rect x="20" y="40" width="160" height="60" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5" stroke-dasharray="6 4"/>
+<text x="100" y="66" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">spec</text>
+<text x="100" y="83" text-anchor="middle" font-size="11.5" fill="#57606a">if screen or spec: true</text>
+<rect x="200" y="40" width="160" height="60" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="280" y="66" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">code</text>
+<text x="280" y="83" text-anchor="middle" font-size="11.5" fill="#57606a">test first</text>
+<rect x="380" y="40" width="160" height="60" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="460" y="66" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">review</text>
+<text x="460" y="83" text-anchor="middle" font-size="11.5" fill="#57606a">code</text>
+<rect x="560" y="40" width="160" height="60" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5" stroke-dasharray="6 4"/>
+<text x="640" y="66" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">correction</text>
+<text x="640" y="83" text-anchor="middle" font-size="11.5" fill="#57606a">if not compliant</text>
+<rect x="740" y="40" width="160" height="60" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5" stroke-dasharray="6 4"/>
+<text x="820" y="66" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">UX</text>
+<text x="820" y="83" text-anchor="middle" font-size="11.5" fill="#57606a">if visible</text>
+<rect x="920" y="40" width="160" height="60" rx="6" fill="#ddf4ff" stroke="#0969da" stroke-width="2"/>
+<text x="1000" y="66" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">ready</text>
+<text x="1000" y="83" text-anchor="middle" font-size="11.5" fill="#57606a">integrated (worktree mode)</text>
+<polyline points="180,70 198,70" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr)"/>
+<polyline points="360,70 378,70" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr)"/>
+<polyline points="540,70 558,70" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr)"/>
+<polyline points="720,70 738,70" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr)"/>
+<polyline points="900,70 918,70" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr)"/>
+<polyline points="640,40 640,22 460,22 460,38" fill="none" stroke="#57606a" stroke-width="1.5" stroke-dasharray="5 3" marker-end="url(#arr)"/>
+<text x="550" y="16" text-anchor="middle" font-size="11.5" fill="#57606a">back to the review after each correction</text>
+<rect x="20" y="180" width="160" height="56" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1"/>
+<text x="100" y="204" text-anchor="middle" font-size="12.5" font-weight="600" fill="#1f2328">spec-writer</text>
+<text x="100" y="222" text-anchor="middle" font-size="11.5" fill="#57606a">then reviewer</text>
+<rect x="200" y="180" width="160" height="56" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1"/>
+<text x="280" y="204" text-anchor="middle" font-size="12.5" font-weight="600" fill="#1f2328">fresh session</text>
+<text x="280" y="222" text-anchor="middle" font-size="11.5" fill="#57606a">of the program</text>
+<rect x="380" y="180" width="160" height="56" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1"/>
+<text x="460" y="204" text-anchor="middle" font-size="12.5" font-weight="600" fill="#1f2328">code-reviewer</text>
+<text x="460" y="222" text-anchor="middle" font-size="11.5" fill="#57606a">agent</text>
+<rect x="560" y="180" width="160" height="56" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1"/>
+<text x="640" y="204" text-anchor="middle" font-size="12.5" font-weight="600" fill="#1f2328">fresh session</text>
+<text x="640" y="222" text-anchor="middle" font-size="11.5" fill="#57606a">2 passes, 3 if it converges</text>
+<rect x="740" y="180" width="160" height="56" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1"/>
+<text x="820" y="204" text-anchor="middle" font-size="12.5" font-weight="600" fill="#1f2328">ux-reviewer</text>
+<text x="820" y="222" text-anchor="middle" font-size="11.5" fill="#57606a">then the human</text>
+<rect x="920" y="180" width="160" height="56" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1"/>
+<text x="1000" y="204" text-anchor="middle" font-size="12.5" font-weight="600" fill="#1f2328">the lead</text>
+<text x="1000" y="222" text-anchor="middle" font-size="11.5" fill="#57606a">re-checks, raf done</text>
+<text x="550" y="270" text-anchor="middle" font-size="11.5" fill="#57606a">Dashed: a conditional step. The program chains the sessions; the verdicts of the review and of the UX pass are recorded in the plan.</text>
+</svg>

package/docs/concepts-vague-dark.svg

@@ -0,0 +1,39 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1100 390" width="1100" height="390" role="img" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif" font-size="13" fill="#e6edf3">
+<title>Wave and slots</title>
+<desc>A wave plays its lots in fresh sessions under a cap of slots; a lot waits in the queue until a slot is free, and a session the lead started by hand is held and takes a slot.</desc>
+<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></defs>
+<rect width="1100" height="390" fill="#0d1117"/>
+<rect x="20" y="44" width="170" height="240" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="105" y="160" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">Queue</text>
+<text x="105" y="177" text-anchor="middle" font-size="11.5" fill="#8b949e">lots waiting, in the</text>
+<text x="105" y="190" text-anchor="middle" font-size="11.5" fill="#8b949e">priority order</text>
+<text x="105" y="222" text-anchor="middle" font-size="11.5" fill="#8b949e">a lot that depends on</text>
+<text x="105" y="238" text-anchor="middle" font-size="11.5" fill="#8b949e">another waits for it</text>
+<text x="230" y="26" text-anchor="start" font-size="11.5" font-weight="600" fill="#e6edf3">SLOTS: as many sessions at once as the cap (CADENCE_MAX_SESSIONS)</text>
+<rect x="270" y="44" width="380" height="52" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="460" y="66" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">slot 1 · L1</text>
+<text x="460" y="83" text-anchor="middle" font-size="11.5" fill="#8b949e">implementation: a session running</text>
+<polyline points="190,164 268,70" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr)"/>
+<rect x="270" y="108" width="380" height="52" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="460" y="130" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">slot 2 · L2</text>
+<text x="460" y="147" text-anchor="middle" font-size="11.5" fill="#8b949e">review: a session running</text>
+<polyline points="190,164 268,134" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr)"/>
+<rect x="270" y="172" width="380" height="52" rx="6" fill="#0c2d6b" stroke="#58a6ff" stroke-width="2" stroke-dasharray="6 4"/>
+<text x="460" y="194" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">slot 3 · hold</text>
+<text x="460" y="211" text-anchor="middle" font-size="11.5" fill="#8b949e">a fix started by hand by the lead</text>
+<polyline points="190,164 268,198" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr)"/>
+<rect x="270" y="236" width="380" height="52" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5" stroke-dasharray="6 4"/>
+<text x="460" y="258" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">slot 4 · free</text>
+<text x="460" y="275" text-anchor="middle" font-size="11.5" fill="#8b949e">with --continue, the next ready lot is drawn</text>
+<polyline points="190,164 268,262" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr)"/>
+<rect x="740" y="44" width="200" height="80" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="840" y="80" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">Table of the wave</text>
+<text x="840" y="97" text-anchor="middle" font-size="11.5" fill="#8b949e">ready · handed back · questions</text>
+<polyline points="650,70 738,84" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr)"/>
+<rect x="740" y="170" width="200" height="80" rx="6" fill="#0c2d6b" stroke="#58a6ff" stroke-width="2"/>
+<text x="840" y="206" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">The lead</text>
+<text x="840" y="223" text-anchor="middle" font-size="11.5" fill="#8b949e">relays, re-checks, delivers</text>
+<polyline points="840,124 840,168" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr)"/>
+<text x="550" y="330" text-anchor="middle" font-size="11.5" fill="#8b949e">A hold (cadence lead hold) counts against the cap like a running session: the wave waits for it instead of overtaking it.</text>
+<text x="550" y="352" text-anchor="middle" font-size="11.5" fill="#8b949e">A freed slot goes to the wave queue; with --continue it also draws the next ready lot of the plan.</text>
+</svg>

package/docs/concepts-vague-light.svg

@@ -0,0 +1,39 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1100 390" width="1100" height="390" role="img" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif" font-size="13" fill="#1f2328">
+<title>Wave and slots</title>
+<desc>A wave plays its lots in fresh sessions under a cap of slots; a lot waits in the queue until a slot is free, and a session the lead started by hand is held and takes a slot.</desc>
+<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="#57606a"/></marker></defs>
+<rect width="1100" height="390" fill="#ffffff"/>
+<rect x="20" y="44" width="170" height="240" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="105" y="160" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">Queue</text>
+<text x="105" y="177" text-anchor="middle" font-size="11.5" fill="#57606a">lots waiting, in the</text>
+<text x="105" y="190" text-anchor="middle" font-size="11.5" fill="#57606a">priority order</text>
+<text x="105" y="222" text-anchor="middle" font-size="11.5" fill="#57606a">a lot that depends on</text>
+<text x="105" y="238" text-anchor="middle" font-size="11.5" fill="#57606a">another waits for it</text>
+<text x="230" y="26" text-anchor="start" font-size="11.5" font-weight="600" fill="#1f2328">SLOTS: as many sessions at once as the cap (CADENCE_MAX_SESSIONS)</text>
+<rect x="270" y="44" width="380" height="52" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="460" y="66" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">slot 1 · L1</text>
+<text x="460" y="83" text-anchor="middle" font-size="11.5" fill="#57606a">implementation: a session running</text>
+<polyline points="190,164 268,70" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr)"/>
+<rect x="270" y="108" width="380" height="52" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="460" y="130" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">slot 2 · L2</text>
+<text x="460" y="147" text-anchor="middle" font-size="11.5" fill="#57606a">review: a session running</text>
+<polyline points="190,164 268,134" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr)"/>
+<rect x="270" y="172" width="380" height="52" rx="6" fill="#ddf4ff" stroke="#0969da" stroke-width="2" stroke-dasharray="6 4"/>
+<text x="460" y="194" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">slot 3 · hold</text>
+<text x="460" y="211" text-anchor="middle" font-size="11.5" fill="#57606a">a fix started by hand by the lead</text>
+<polyline points="190,164 268,198" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr)"/>
+<rect x="270" y="236" width="380" height="52" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5" stroke-dasharray="6 4"/>
+<text x="460" y="258" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">slot 4 · free</text>
+<text x="460" y="275" text-anchor="middle" font-size="11.5" fill="#57606a">with --continue, the next ready lot is drawn</text>
+<polyline points="190,164 268,262" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr)"/>
+<rect x="740" y="44" width="200" height="80" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="840" y="80" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">Table of the wave</text>
+<text x="840" y="97" text-anchor="middle" font-size="11.5" fill="#57606a">ready · handed back · questions</text>
+<polyline points="650,70 738,84" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr)"/>
+<rect x="740" y="170" width="200" height="80" rx="6" fill="#ddf4ff" stroke="#0969da" stroke-width="2"/>
+<text x="840" y="206" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">The lead</text>
+<text x="840" y="223" text-anchor="middle" font-size="11.5" fill="#57606a">relays, re-checks, delivers</text>
+<polyline points="840,124 840,168" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr)"/>
+<text x="550" y="330" text-anchor="middle" font-size="11.5" fill="#57606a">A hold (cadence lead hold) counts against the cap like a running session: the wave waits for it instead of overtaking it.</text>
+<text x="550" y="352" text-anchor="middle" font-size="11.5" fill="#57606a">A freed slot goes to the wave queue; with --continue it also draws the next ready lot of the plan.</text>
+</svg>

package/docs/concepts-worktrees-dark.svg

@@ -0,0 +1,45 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1100 330" width="1100" height="330" role="img" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif" font-size="13" fill="#e6edf3">
+<title>Worktrees to main</title>
+<desc>Each lot works on its own branch in its own worktree; at the end of its cycle it is rebased onto the tip of main, its checks are replayed, and it is fast-forwarded into main one lot at a time under a lock.</desc>
+<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></defs>
+<rect width="1100" height="330" fill="#0d1117"/>
+<rect x="20" y="30" width="200" height="56" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="120" y="54" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">worktree L1</text>
+<text x="120" y="71" text-anchor="middle" font-size="11.5" fill="#8b949e">cadence/&lt;wave&gt;/&lt;project&gt;--L1</text>
+<rect x="280" y="30" width="180" height="56" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="370" y="54" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">cycle</text>
+<text x="370" y="71" text-anchor="middle" font-size="11.5" fill="#8b949e">code · review · UX</text>
+<polyline points="220,58 278,58" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr)"/>
+<polyline points="460,58 518,58" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr)"/>
+<rect x="20" y="110" width="200" height="56" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="120" y="134" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">worktree L2</text>
+<text x="120" y="151" text-anchor="middle" font-size="11.5" fill="#8b949e">cadence/&lt;wave&gt;/&lt;project&gt;--L2</text>
+<rect x="280" y="110" width="180" height="56" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="370" y="134" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">cycle</text>
+<text x="370" y="151" text-anchor="middle" font-size="11.5" fill="#8b949e">code · review · UX</text>
+<polyline points="220,138 278,138" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr)"/>
+<polyline points="460,138 518,138" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr)"/>
+<rect x="20" y="190" width="200" height="56" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="120" y="214" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">worktree L3</text>
+<text x="120" y="231" text-anchor="middle" font-size="11.5" fill="#8b949e">cadence/&lt;wave&gt;/&lt;project&gt;--L3</text>
+<rect x="280" y="190" width="180" height="56" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="370" y="214" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">cycle</text>
+<text x="370" y="231" text-anchor="middle" font-size="11.5" fill="#8b949e">code · review · UX</text>
+<polyline points="220,218 278,218" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr)"/>
+<polyline points="460,218 518,218" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr)"/>
+<rect x="520" y="30" width="240" height="216" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="640" y="142" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3"></text>
+<text x="640" y="56" text-anchor="middle" font-size="13.5" font-weight="600" fill="#e6edf3">Integration</text>
+<text x="640" y="120" text-anchor="middle" font-size="11.5" fill="#e6edf3">one lot at a time (lock)</text>
+<text x="640" y="142" text-anchor="middle" font-size="11.5" fill="#8b949e">1. rebase onto the tip of main</text>
+<text x="640" y="160" text-anchor="middle" font-size="11.5" fill="#8b949e">2. replay the checks</text>
+<text x="640" y="178" text-anchor="middle" font-size="11.5" fill="#8b949e">3. fast-forward main</text>
+<text x="640" y="200" text-anchor="middle" font-size="11.5" fill="#8b949e">main moved? replay, twice at most</text>
+<polyline points="760,138 858,138" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr)"/>
+<rect x="860" y="100" width="220" height="76" rx="6" fill="#0c2d6b" stroke="#58a6ff" stroke-width="2"/>
+<text x="970" y="134" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">main</text>
+<text x="970" y="151" text-anchor="middle" font-size="11.5" fill="#8b949e">linear history, then ready</text>
+<text x="970" y="196" text-anchor="middle" font-size="11.5" fill="#8b949e">the plan is written here, by the program</text>
+<text x="550" y="280" text-anchor="middle" font-size="11.5" fill="#8b949e">orchestrate.worktrees: true lets independent lots of one repository play at the same time.</text>
+<text x="550" y="300" text-anchor="middle" font-size="11.5" fill="#8b949e">Without it, lots play one after the other in the repository itself.</text>
+</svg>

package/docs/concepts-worktrees-light.svg

@@ -0,0 +1,45 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1100 330" width="1100" height="330" role="img" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif" font-size="13" fill="#1f2328">
+<title>Worktrees to main</title>
+<desc>Each lot works on its own branch in its own worktree; at the end of its cycle it is rebased onto the tip of main, its checks are replayed, and it is fast-forwarded into main one lot at a time under a lock.</desc>
+<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="#57606a"/></marker></defs>
+<rect width="1100" height="330" fill="#ffffff"/>
+<rect x="20" y="30" width="200" height="56" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="120" y="54" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">worktree L1</text>
+<text x="120" y="71" text-anchor="middle" font-size="11.5" fill="#57606a">cadence/&lt;wave&gt;/&lt;project&gt;--L1</text>
+<rect x="280" y="30" width="180" height="56" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="370" y="54" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">cycle</text>
+<text x="370" y="71" text-anchor="middle" font-size="11.5" fill="#57606a">code · review · UX</text>
+<polyline points="220,58 278,58" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr)"/>
+<polyline points="460,58 518,58" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr)"/>
+<rect x="20" y="110" width="200" height="56" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="120" y="134" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">worktree L2</text>
+<text x="120" y="151" text-anchor="middle" font-size="11.5" fill="#57606a">cadence/&lt;wave&gt;/&lt;project&gt;--L2</text>
+<rect x="280" y="110" width="180" height="56" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="370" y="134" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">cycle</text>
+<text x="370" y="151" text-anchor="middle" font-size="11.5" fill="#57606a">code · review · UX</text>
+<polyline points="220,138 278,138" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr)"/>
+<polyline points="460,138 518,138" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr)"/>
+<rect x="20" y="190" width="200" height="56" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="120" y="214" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">worktree L3</text>
+<text x="120" y="231" text-anchor="middle" font-size="11.5" fill="#57606a">cadence/&lt;wave&gt;/&lt;project&gt;--L3</text>
+<rect x="280" y="190" width="180" height="56" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="370" y="214" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">cycle</text>
+<text x="370" y="231" text-anchor="middle" font-size="11.5" fill="#57606a">code · review · UX</text>
+<polyline points="220,218 278,218" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr)"/>
+<polyline points="460,218 518,218" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr)"/>
+<rect x="520" y="30" width="240" height="216" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="640" y="142" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328"></text>
+<text x="640" y="56" text-anchor="middle" font-size="13.5" font-weight="600" fill="#1f2328">Integration</text>
+<text x="640" y="120" text-anchor="middle" font-size="11.5" fill="#1f2328">one lot at a time (lock)</text>
+<text x="640" y="142" text-anchor="middle" font-size="11.5" fill="#57606a">1. rebase onto the tip of main</text>
+<text x="640" y="160" text-anchor="middle" font-size="11.5" fill="#57606a">2. replay the checks</text>
+<text x="640" y="178" text-anchor="middle" font-size="11.5" fill="#57606a">3. fast-forward main</text>
+<text x="640" y="200" text-anchor="middle" font-size="11.5" fill="#57606a">main moved? replay, twice at most</text>
+<polyline points="760,138 858,138" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr)"/>
+<rect x="860" y="100" width="220" height="76" rx="6" fill="#ddf4ff" stroke="#0969da" stroke-width="2"/>
+<text x="970" y="134" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">main</text>
+<text x="970" y="151" text-anchor="middle" font-size="11.5" fill="#57606a">linear history, then ready</text>
+<text x="970" y="196" text-anchor="middle" font-size="11.5" fill="#57606a">the plan is written here, by the program</text>
+<text x="550" y="280" text-anchor="middle" font-size="11.5" fill="#57606a">orchestrate.worktrees: true lets independent lots of one repository play at the same time.</text>
+<text x="550" y="300" text-anchor="middle" font-size="11.5" fill="#57606a">Without it, lots play one after the other in the repository itself.</text>
+</svg>

package/docs/concepts.md

@@ -0,0 +1,159 @@
+[← cadence](../README.md)
+
+# The notions of cadence, for a human
+
+cadence has become a rich tool, and its vocabulary comes faster than its pages. This one explains each notion in a few sentences,
+**in the order you meet them**, with four figures; the technical detail stays in the pages it links, and the
+[glossary](#glossary) at the end is the one-line version. You do not need to know cadence to read it: the journey of a lot
+([figure 1](#the-steps-of-a-lot)) is the five minutes to keep if you keep only one thing.
+
+## Plan and lot
+
+The **plan** is a file in your repository (`.cadence/raf.yaml`): the list of what is left to do and what was done.
+Each item is a **lot**: a piece of work small enough to be finished in a day or two, with an identifier (`L12`), a title, an
+estimate and a status (`todo`, `doing`, `done`, or `dropped`). A commit that belongs to a lot cites it in its subject:
+`feat(L12): …`. That link is the whole idea: from any commit you know what it was for, from any lot you know its commits.
+The `raf` command reads and writes the plan; `raf check` lists the commits that cite no lot. Detail: [raf.md](raf.md).
+
+## Verdicts
+
+A lot is not finished when its code is written, but when two independent readers said so, and the plan keeps their word:
+the **review verdict** (`raf review`) says the code is compliant, the **UX verdict** (`raf ux`) says the screen is
+usable, for a lot that shows one (a `visible` lot). A verdict is recorded by the program (the review) or by the lead (the UX verdict, on the human's word), not by
+the session that wrote the code. `raf done` is refused while a sub-task is open. Detail: [raf.md](raf.md), [news.md](news.md).
+
+## Session and wave
+
+A **session** is one fresh run of Claude Code with a brief and a single job (write the spec, write the code, review, fix). It
+remembers nothing of the previous one: what it needs is in the brief and in the repository. A **wave** is a run of
+`cadence orchestrate` over several lots: the program (not a model) starts the sessions, chains the steps of each lot, runs
+the tests, and prints a final table with the lots ready and the lots handed back. A session cannot ask you anything: when it is
+stuck it stops and reports, and the question comes back to you through the lead. Detail: [orchestrate.md](orchestrate.md).
+
+## The steps of a lot
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="concepts-lot-dark.svg">
+  <img alt="A lot goes through spec, code, review, correction, UX and ready; under each step, who does it: spec-writer, a fresh session, the code-reviewer, a fresh session, the ux-reviewer, the lead" src="concepts-lot-light.svg">
+</picture>
+
+Inside a wave, a lot goes through these steps, each in a fresh session. Dashed boxes are conditional.
+
+| Step | What happens | Who |
+|---|---|---|
+| **spec** | For a lot that creates a screen (`screen: page`) or has a behaviour to pin down (`spec: true`): a mockup and a **sheet** (fields, states, numbered rules); reviewed before any code, and the acceptance tests are written from it, committed red and locked | the `spec-writer` agent, reviewed by the `ux-reviewer` (mockup) or the `code-reviewer` (sheet); then the `acceptance-writer` agent, a separate session, writes the tests; the program locks them |
+| **code** | Test first, then the code, commits that cite the lot; the lot's own tests must pass | a fresh session of the program |
+| **review** | Reads the diff against the lot (and the sheet, rule by rule) and returns findings: blocking, major, minor | the `code-reviewer` agent; the program records `raf review` when it is compliant |
+| **correction** | Only if the review is not compliant: a new session fixes the findings, then a new review. Two passes at most, three when the findings converge; then the lot is **handed back** | a fresh session; the program decides how many |
+| **UX** | For a visible lot: the screen is opened in a real browser, in each state, with captures at 1440 and 390 px | the `ux-reviewer` agent for the report; the verdict is **the human's**, or the lead's when the parent folder says `lead.ux: lead` |
+| **ready** | In worktree mode the lot is integrated (see [below](#one-worktree-per-lot-and-integration)); without worktree (the default) it is ready as soon as its review is compliant; the lead re-checks it, records `raf done`, delivers it | the lead |
+
+Before all that, a lot whose title cites a finding or another lot gets a **precheck**: « is it already done? ». Small lots (half a day or
+less) get a single review pass. Detail: [fonctionnement.md](fonctionnement.md#2-a-lot-inside-a-wave), [spec.md](spec.md).
+
+## The test gate
+
+After each writing session the program plays the project's own **gate**: the build (`orchestrate.build`), then the tests
+(`orchestrate.test`). A session's « the tests pass » is never taken on trust. Three rules keep the gate honest:
+
+- **Already red at the start.** If a test fails, the program replays the suite at the sha the lot started from, in a **throwaway copy**
+  of the repository (a temporary `git worktree` outside it, removed afterwards). A test that was already red is not the lot's fault: no correction pass,
+  and the table lists it apart.
+- **Replayed alone.** With `orchestrate.testReplay`, a test red in the whole suite is replayed alone: green alone means a load
+  failure, not a defect, so no correction is spent on it. Without this key, nothing is replayed.
+- **A test that reads the plan.** The commits that only touch the plan are crossed when the gate's verdict is carried over them. A project whose
+  tests read `.cadence/raf.yaml` says so with `orchestrate.gate: { readsPlan: true }`, or the gate would not see a break.
+
+A **resume** (`cadence orchestrate --resume`) picks a suspended or handed-back wave where it stopped, instead of starting again.
+Detail: [orchestrate.md](orchestrate.md#orchestrate), [deliver.md](deliver.md), [remote-gate.md](remote-gate.md).
+
+## One worktree per lot, and integration
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="concepts-worktrees-dark.svg">
+  <img alt="Three lots each work in their own worktree on their own branch; at the end of their cycle they pass one at a time through the integration (rebase, replayed checks, fast-forward) into main" src="concepts-worktrees-light.svg">
+</picture>
+
+By default a wave plays the lots of a repository one after the other. With `orchestrate.worktrees: true`, independent lots play **at the same
+time**, each in its own **worktree** (a second checkout of the same repository, in its own folder) on its own branch
+`cadence/<wave>/<project>--<lot>`, so two sessions never edit the same files. When a lot's cycle ends, the program **integrates** it: one
+lot at a time under a lock, it rebases the branch on the tip of `main`, replays the checks, and fast-forwards `main`. Only then is the
+lot `ready`. If `main` moved in the meantime the rebase is replayed, twice at most, then the lot is handed back. Two rules protect
+you: the program, not the sessions, writes the plan; and a session never commits on the `main` branch of another repository
+(it uses a `wip/` branch). Detail: [orchestrate.md](orchestrate.md#one-worktree-per-lot-orchestrateworktrees-l279).
+
+## Deliverable up to a sha
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="concepts-livraison-dark.svg">
+  <img alt="Commits stack on main: L1 and L2 are ready, L3 is handed back, L4 is ready above it; the deliverable sha is the last commit of L2, so L3 and L4 are not pushed" src="concepts-livraison-light.svg">
+</picture>
+
+Lots commit on top of each other on `main`. When a ready lot sits **under** a lot that is not ready, pushing `HEAD` would also publish
+unreviewed code. The final table then says « **livrable jusqu'à `<sha>`** »: the last commit of the highest ready lot that has no
+unfinished lot beneath it. You ship exactly that, and nothing above:
+
+```sh
+git push origin <sha>:main && cadence deliver --sha <sha>
+```
+
+`cadence deliver` waits for the CI of that exact sha, deploys, and replays the effect checks: a delivery is finished only when its effect is proved.
+Where the project declares a gate, the `pre-push` hook refuses a sha with no green `cadence verify --gate`. Detail: [deliver.md](deliver.md), [orchestrate.md](orchestrate.md#orchestrate).
+
+## Lead and delivery agent
+
+The **lead** is a Claude Code session (`/cadence:lead`) that drives the waves for you: it reads the state of every project
+(`cadence lead tour`), proposes lots, starts the waves, relays each line of the journal and each question, **re-verifies** what comes back
+(git log, tests, build, `raf check`), then delivers. It never codes and never commits where a wave runs. The **delivery agent**
+(`livreur`) is a subagent the lead hands one ready lot to: it checks the sha, runs the gate, records `raf done`, pushes the sha and
+delivers, then reports in one line. You stay the one who decides what matters, and the UX verdict if you did not delegate it.
+Detail: [lead.md](lead.md), [skills.md](skills.md).
+
+## Slots and holds
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="concepts-vague-dark.svg">
+  <img alt="A queue of lots feeds the slots of a wave: two sessions running, a slot held by a fix the lead started by hand, a free slot that `--continue` fills from the plan; the wave's table goes to the lead" src="concepts-vague-light.svg">
+</picture>
+
+The machine and your quota are shared, so at most **N sessions run at once**: N is the cap (`CADENCE_MAX_SESSIONS` or `--max-sessions`, 2 by default;
+the lead never raises it itself). Each running session occupies a **slot**; a lot waits in the queue until one is free, and a freed slot goes to the next
+lot of the wave's queue; with `--continue`, a freed slot is also filled at once by the next ready lot of the plan; without it, nothing is drawn from the plan. A session the lead starts by hand (a fix, a QA pass) is invisible to the waves, so
+the lead declares it with `cadence lead hold <label>` and lifts it with `cadence lead release <label>`: a **hold** takes a slot, and
+the waves wait for it instead of overtaking it. `cadence orchestrate --status` prints `créneaux libres : 1 sur 3`. Detail: [lead.md](lead.md#lead-hold-and-release), [orchestrate.md](orchestrate.md#orchestrate).
+
+## Escalation
+
+A lot that is still not compliant after its correction passes would normally be handed back. A project can ask for one more try
+with a stronger model: `orchestrate.escalation: { model: fable }` plays one correction and one fresh review on that model first
+(absent, nothing changes; it costs a share of the lot's budget). If that is not enough, the lot is **handed back** to the lead,
+who either fixes it, answers the question, or brings it to you: the question always reaches a human, never a session. Detail: [orchestrate.md](orchestrate.md#orchestrate), [perf.md](perf.md).
+
+## Putting into service and release
+
+Two moments are easy to confuse. **Putting into service** concerns cadence itself, where the `raf` and `cadence` commands you type must
+not run the code a wave is rewriting: they read a separate copy, updated only by `npm run service -- <sha>`, which refuses a sha
+that is not an ancestor of `HEAD` or whose lots are not `done`. A **release** is a published version: `cadence release patch|minor|major` writes the version
+files and the changelog, then prints the steps the lead plays (tag, gate, push, CI, publication). Detail: [fonctionnement.md](fonctionnement.md#4-putting-cadence-itself-in-service), [releasing.md](releasing.md).
+
+## Glossary
+
+- **plan**: the file `.cadence/raf.yaml` that lists the lots; the single source of truth.
+- **lot**: one item of the plan, cited by its commits (`feat(L12): …`).
+- **verdict**: the recorded opinion of a reviewer on a lot: `raf review` (code) and `raf ux` (screen).
+- **session**: one fresh Claude Code run with a brief and one job.
+- **wave**: a `cadence orchestrate` run that plays several lots and prints a table of what is ready and what is handed back.
+- **sheet**: the written spec of a screen or a behaviour, with numbered rules, each tested.
+- **gate**: the build and the tests the program plays after each session, with the already-red baseline and the replay alone.
+- **readsPlan**: `orchestrate.gate` key declaring that a test reads the plan, so plan-only commits are not crossed.
+- **worktree**: a second checkout of the repository on its own branch, one per lot, so lots play at the same time.
+- **integration**: rebasing a lot on the tip of `main`, replaying the checks and fast-forwarding, one lot at a time, before `ready`.
+- **handed back**: a lot the wave could not finish and returns to the lead with its cause.
+- **deliverable up to**: the sha up to which a delivery is safe, below the first lot that is not ready.
+- **lead**: the session that drives the waves, re-verifies and delivers; it never codes.
+- **delivery agent**: the `livreur` subagent that delivers one ready lot and reports in one line.
+- **slot**: one place under the cap of simultaneous sessions.
+- **hold**: a slot kept by a session the lead started by hand, so waves do not overtake it.
+- **escalation**: one more correction and review on a stronger model before a lot is handed back.
+- **service**: the separate copy of cadence the `PATH` commands read, updated by `npm run service -- <sha>`.
+- **release**: a published version, prepared by `cadence release`.

package/docs/fonctionnement.md

@@ -1,5 +1,7 @@
 # How cadence works
 
+New to the vocabulary? Start with [the notions of cadence](concepts.md); this page is the mechanics.
+
 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

package/docs/lead.md

@@ -158,7 +158,7 @@ cadence config set orchestrate.build 'npx tsc --noEmit' --all
 - `<key>` is a dotted path (`orchestrate.escalation`); `<value>` is read as YAML, so `true`, a command, or a flow mapping like `{ model: fable }` all work. A key already at that value is left alone.
 - The rest of the file is kept as it is, byte for byte — comments, key order, blank lines, inline lists (`[a, b]`) and mappings: only the lines of the key change (a new key goes at the end of its parent; a value replaced in place keeps its end-of-line comment). The only exception is a file whose rewrite by the YAML library moves lines other than the key's (its line count changes, a comment lands on another line, or the lines carried over would not read back as the same document): then the whole file is rewritten in the library's style. A project with no `cadence.yaml` gets one.
 - In each project it creates a **config lot** that quotes the key (`config cadence.yaml : <key> = <value>`, estimate 0.05), as `raf add` then `raf start` would, and commits `cadence.yaml`, the plan file and, when the project names `plan.onWrite`, the files that command produces (it runs when the plan is written; see `docs/raf.md`) with explicit paths (`chore(L12): cadence.yaml — <key> = <value>`): nothing else in the index or the working tree goes in. The lot is left `doing`: closing it (`raf done`) stays the lead's step. **Nothing is pushed.**
-- The new text is read back with cadence's own config loaders (plan, news, hook, perf, session, orchestrate, docs, references, migrate, lead.ux, depth, priority, deliver) before anything is written. A `cadence.yaml` that does not read back — before the change or after it — **stops the run** (exit code 1) at that project, with nothing written there; the projects after it are named `non traités`. A commit the repository refuses (a hook) or a `plan.onWrite` command that fails stops it the same way (`lot ou commit impossible`), `cadence.yaml`, the plan file and the produced files put back as they were (a produced file HEAD does not know is deleted).
+- The new text is read back with cadence's own config loaders (plan, news, hook, perf, session, orchestrate, docs, references, migrate, memory, lead.ux, depth, priority, deliver) before anything is written. A `cadence.yaml` that does not read back — before the change or after it — **stops the run** (exit code 1) at that project, with nothing written there; the projects after it are named `non traités`. A commit the repository refuses (a hook) or a `plan.onWrite` command that fails stops it the same way (`lot ou commit impossible`), `cadence.yaml`, the plan file and the produced files put back as they were (a produced file HEAD does not know is deleted).
 - A project is **skipped**, with the reason, when: it is not its own git repository; the key is already at that value; the key cannot be set in its file (a plain value in the way); `cadence.yaml`, the plan file or a file named by `plan.onWrite.files` has uncommitted changes (the explicit-path commit would take them); or its plan is read-only (kept by another tool) and `cadence.yaml` names no creation command. A read-only plan that names one with `plan.add` (a shell command containing `{title}`, replaced by the quoted title of the config lot, e.g. `plan: { path: taches.yaml, lots: taches, add: 'mytool add {title}' }`) gets its config lot from that command, run in the project folder; the lot id is the first id-like word of its output (the commit subject has none when there is none), and `cadence.yaml` and the plan file are committed together. The command alone decides the lot's status.
 - `--dry-run` prints the same lines, prefixed `+ … serait fait`, and writes and commits nothing. The last line counts what was done and skipped. Without `--all` the command refuses (run `raf`/an editor inside the project for a single one).
 
@@ -194,6 +194,8 @@ After the project lines the tour lists the **worktrees kept by waves** (L279, `o
 
 Before the project lines the tour prints the **perf header** (L227): one line per `⚠` of `cadence perf` for the folder, in the order of `perf`, each ending with its decision and, for a trend, the value of its quality twin (speed and quality side by side); the net-bottleneck `⚠ goulot` line is relayed as is. Nothing is printed when no `⚠` stands, and the output is then the one of a tour without header. The header is read with `perf`'s own reading of the folder (projects up to two levels, whatever `--depth`) and only in the text output: `--json` is unchanged. When `perf` cannot read the folder (no `.cadence/runs`, malformed price grid, unreadable journals or plans) the tour prints no header, reports no perf error and exits 0. The [lead skill](skills.md) reads the header before proposing the three lots and opens an improvement lot only on a trend confirmed on two windows or a net bottleneck.
 
+After the worktree lines the tour prints, when the `MEMORY.md` index of Claude Code for the parent folder outgrows its threshold (L442), `mémoire · MEMORY.md 15700 octets > seuil 12000 · 14 entrée(s) datée(s) à regrouper (cadence session close détaille)`. The index is `projects/<parent folder>/memory/MEMORY.md` under the Claude Code folder (`CLAUDE_CONFIG_DIR`, else the default one) (the folder resolved from the argument of `lead tour`); the threshold is 12000 bytes, or `memory.indexMaxBytes` in the parent folder's `cadence.yaml`, the same key and the same rule as for `cadence session close` ([docs/session.md](session.md#memory-index-size-l442)). A value that is not an integer ≥ 1 does not stop the tour (exit code 0): the line `cadence.yaml · ✗ erreur : memory.indexMaxBytes doit être un entier ≥ 1 (octets), pas <valeur>` replaces it. An unreadable index prints `mémoire · MEMORY.md illisible (<cause>)`. Nothing is printed for an absent index or one at the threshold, `--json` is unchanged, and the tour never writes the memory: the [lead skill](skills.md) relays the line and proposes the grouping, which is done once the human agrees.
+
 When an orchestrated wave is live, one more line closes the tour (not part of `--json`): `vagues en cours : 1 · sessions en cours : 0 · créneaux libres : 1 sur 2` — the lead reads the free slots there instead of computing them (L141). The `sur M` is the cap the human set (`CADENCE_MAX_SESSIONS`, 2 by default), not a fixed 2 (L208); an invalid value falls back to 2 in this display. The sessions held with [`lead hold`](#lead-hold-and-release) are subtracted from the free slots. The line is always printed (L416), with no live wave and no held session too: `vagues en cours : 0 · sessions en cours : 0 · créneaux libres : 3 sur 3`, so that an empty slot is read, not deduced from a missing line.
 
 Next to it, when at least one ready lot is free, a line `prêts, ressources libres : alpha:L3 <title> · beta:L2 <title> (banc)` (L252, GitHub issue #13, 2/3) lists, for every project of the tour, the ready lots (same rule as `next`, minus the ones marked « à décider ») that can start now: a lot is free when none of the resources in its `uses:` (shown in parentheses) is held by a lot `doing` in any project of the tour or in any project that shares its resources (the projects under the folder whose `cadence.yaml` declares `resources:`, walked with that file's `depth:`, one level by default, so `P/x` and `P/grp/alpha` share the `banc` of `P/cadence.yaml` with `depth: 2` wherever the tour is launched from, even from inside one project; with no declared resource, the projects of the parent folder), nor by an unfinished lot of a live wave (a wave's lot is recognised by its repository and its id, not by the project name: a nested project `grp/alpha` matches the wave launched from `grp/` that cites it as `alpha`, and a wave launched from another folder only hides the lots of its own repositories); a lot with no `uses:` holds none and is always free. The line shows at most 3 lots per project, then `alpha +K` for the others. Like the slots line it is always printed (L416), whether or not a wave is live or a session is held. It is a display: nothing locks, `raf start` and `orchestrate` still start a lot whose resource is taken. `--json` gives the same lots, always, as a `free` array on each project (`id`, `title`, and `uses` when the lot has any; absent when the project has none).

package/docs/orchestrate.md

@@ -561,6 +561,10 @@ except a copy that is still needed, which stays and is said: a copy that a live
 The waves that count are those of the launch folders the script knows (`<folder>/.cadence/runs/<wave>/wave.json`): the repository itself and the working directory of every wave the orchestrator's registry still lists (`~/.cadence/orchestrate/waves/<pid>.json`; the registry drops a dead wave when another registers, so it does not know suspended waves by itself). There is no search over the whole disk: a suspended wave launched from another folder is not protected here, and `--resume` repairs its snapshot instead (above). A wave never marked `done` keeps its copy until it is, or until its folder is removed. A failure of the purge (unreadable copy, busy file) once `service` and the links have switched is a warning on the error output (`avertissement : purge des anciennes copies interrompue …`): the new version is in service, the fingerprint is printed, the exit code is 0, the next put in service tries again. The same run updates the **local copy of the `cadence-hud` mod** (L419), the one `CLAUDE_CODE_PLUGIN_DIRS` makes Claude Code load (`~/.claude/mods/cadence-hud`, `--mod-dir` for another folder): `plugins/cadence-hud` of the copy just put in service (not the working repository) is synchronised into it with `rsync -a --delete`, which leaves out `.claude-plugin/types` (generated by Claude Code in the copy). The output says `mod cadence-hud : copie locale mise à jour (<dir>)`. A machine without that folder gets no copy created (`copie locale absente … non mise à jour`), and a failed `rsync` is a warning on the error output (`avertissement : mod cadence-hud non mis à jour …`), exit code 0 like the purge: the version is in service. Before L419 the copy was updated by hand at each release and a forgotten one left the old mod loaded. The first run is also what installs the links in `~/.local/bin`. It prints the fingerprint of the copy
 (bin, dist, package.json).
 
+## Proposals the lot's own commits may have treated (L422)
+
+The sub-tasks a review proposes (`[sous-tâche code] …`, `ux`, `maquette`) are returned to the lead in the final table and in `--status --detail <lot>`. When a fix pass runs after the review, it often treats them; 28-10, L230 was opened on proposals already corrected, 5 passes lost. The program now keeps, for each sub-task, the HEAD the review that issued it had read (`proposalHeads` in the lot's state; a later review that repeats the same line does not renew it) and, when it prints the line, looks for the files the text cites (`src/a.ts`, `src/a.ts:42`, `` `docs/z.md` ``; not web addresses nor numbers). If a commit of the lot (those the steps noted, or by default the ones git attributes to it: the HEAD of the review and these shas come from the same state of the branch, whereas the repository's HEAD does not see a lot not yet integrated and only finds rewritten commits once it was rebased) that is not in the history of that HEAD modified one of them (whole path or end of path), the line ends with `— peut-être déjà traitée (<sha>)`, the oldest such commit. It is a hint to check before opening a lot, not a verdict: nothing is removed from the proposals. Left unmarked: minors (already a precise file line), sub-tasks citing no file, states written before this change (no recorded HEAD), a HEAD the repository does not know, a git read that fails, `--status` (compact: the lines are not printed, no git read), and commits made in a neighbouring repository (`repos:`), which are not read.
+
 ## Express lane (L519)
 
 A lot of **at most 0.1 day** (`estimate: 0.1` or less, no `screen:`, no `spec: true`) takes the express lane, with no key to set. The L517 study ([docs/mesures/temps-d-un-lot.md](mesures/temps-d-un-lot.md), lever 2) measures 15.5 min and 116 k counted tokens for such a lot, 44 % of them in review and preparation: the lane cuts about 4.9 min and 51 k tokens per lot. What changes:

package/docs/overview.md

@@ -74,7 +74,7 @@ The two plugins are independent. `cadence@cadence` carries the rituals, which ca
 | [docs/stabilite.md](stabilite.md) | what is guaranteed from 1.0.0 and what is not |
 | [docs/qualite.md](qualite.md) | code-quality guard rails: ESLint (typescript-eslint, sonarjs), knip and jscpd compared to a versioned baseline by a ratchet (`npm run qualite`, `--init`, `--ecrire`, `--migrer`, `--contre`), in the wave's gate and the CI; the recipe for TypeScript, Python, Java and shell |
 
-Also: [news](news.md) (changelog, UX, code and QA reviews, documentation that follows the code), [quality](qualite.md), [session](session.md), [corrections](corrections.md), [perf](perf.md), [skills and agents](skills.md), [cadence-hud](cadence-hud.md), [releasing](releasing.md), [overview](overview.md), [how it all works](fonctionnement.md) (four figures).
+Also: [news](news.md) (changelog, UX, code and QA reviews, documentation that follows the code), [quality](qualite.md), [session](session.md), [corrections](corrections.md), [perf](perf.md), [skills and agents](skills.md), [cadence-hud](cadence-hud.md), [releasing](releasing.md), [overview](overview.md), [the notions, for a human](concepts.md), [how it all works](fonctionnement.md) (four figures).
 
 <details>
 <summary>The four tools in short</summary>

package/docs/session.md

@@ -123,3 +123,35 @@ The command deletes nothing, never fails on the cleanup and does not change the
 The commands get `CADENCE_SINCE` and `CADENCE_TODAY`. `CADENCE_SINCE` is the `--since` as given; on `session close` without `--since` it is the instant of the last `session start` as an ISO 8601 UTC string (`2026-09-28T07:12:00.000Z`), or `<today> 00:00` when no mark exists.
 The commands add facts and decide nothing: a failing command is reported and changes neither
 the exit code nor the verdict.
+
+## Memory index size (L442)
+
+Claude Code loads the `MEMORY.md` index of the folder it was launched in at every turn: a long index is a
+fixed cost of every session. `cadence session close` weighs it and, above a threshold, prints a "Mémoire"
+section:
+
+```
+Mémoire : l'index MEMORY.md pèse 15700 octets (seuil 12000)
+  14 entrée(s) datée(s) (9100 octets) à regrouper sous une ligne vers un index secondaire — le skill propose, l'humain décide
+```
+
+- **Where it looks.** `<CLAUDE_CONFIG_DIR or ~/.claude>/projects/<folder>/memory/MEMORY.md`, where `<folder>` is the
+  working directory of the command (never the git root: Claude Code indexes the folder it was launched in) with every
+  character that is not a letter or a digit replaced by `-`. A symbolic link is followed. With `--all`, each project
+  section weighs its own memory.
+- **When it speaks.** Only when the file is strictly larger than the threshold, in bytes: 12000 by default, or
+  `memory.indexMaxBytes` (an integer ≥ 1) in the `cadence.yaml` the command reads. An absent index, an empty one or
+  one at the threshold prints nothing. A value that is not an integer ≥ 1 stops the close (exit code 2, no report), as
+  `session.cleanDays` does.
+- **Dated entries.** A list line (`- `) whose text starts with a day `dd-mm`, after at most `**`, `[` and `⚠`
+  (`- **[31-10 : …`). The name of the linked file does not count, so the line that points to the secondary index is
+  never counted. With none, the section says `aucune entrée datée à regrouper`.
+- **What it does not do.** It is a proposal, not a condition: the exit code and the « prêt à fermer » line are those of
+  a close without the warning, and cadence never writes the memory. The [session-close skill](skills.md) proposes the
+  grouping and moves the entries only after the human agrees.
+- **Unreadable index** (a folder, no read permission): one line `Mémoire : l'index MEMORY.md est illisible (<cause>), sa taille n'est pas contrôlée`; the rest of the report is printed.
+
+```yaml
+memory:
+  indexMaxBytes: 12000   # bytes; the default
+```

package/docs/whats-new.md

@@ -4,6 +4,7 @@
 
 ## In two lines
 
+- **1.40.0**: `docs/concepts.md`, the notions of cadence for a human; a proposed sub-task maybe already done is flagged; a warning when the memory index loaded every turn grows too big.
 - **1.39.0**: `orchestrate --continue` fills free slots by priority, one worktree per lot when the cap allows (issue #21); waves show their cost in euros before and after.
 - **1.38.1**: `spec green` seals a lot closed at `vert: true` without fingerprints (issue #20); `deliver`, `raf move`, `spec reseal` and `spec green` refuse cleanly during a local task.
 - **1.38.0**: an express lane plays a touch-up of at most 0.1 day in one session; `raf add --local` and `cadence local start|done|abort` lock a repository while the lead edits it by hand.
@@ -68,6 +69,8 @@ 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.40.0**: a guide for humans, `docs/concepts.md`, linked at the top of the README, explains each notion of cadence in a few sentences, in the order you meet them: plan and lot, verdicts, session and wave, the steps of a lot and who plays each, the test gate, worktree and integration, « livrable jusqu'à » (L460). In the final table and `--status --detail`, a proposed sub-task whose cited file was changed by a commit of the lot after the review that proposed it is marked `— peut-être déjà traitée (<sha>)`, so a review no longer feeds the next one with work already done (L422). `cadence session close` and `cadence lead tour` warn when the Claude Code `MEMORY.md` index, loaded at every turn, outgrows a size threshold (`memory.indexMaxBytes`), and propose to group its dated entries behind one line; `cadence config set` reads that key back like the others, so a wrong value stops with nothing written (L442). A measure of the earlier change to the passes, read on two windows of `cadence perf`, is recorded (L430).
+
 **1.39.0**: free slots no longer stay empty (GitHub issue #21, L527, `docs/orchestrate.md`). With `--continue`, once the order is agreed (`--priority` or `priority:` of the parent `cadence.yaml`), the wave starts the next ready lot in each slot as soon as one frees up — a lot handed back at its pre-check frees its slot in seconds —, in priority order, within the session cap, the shared resources and one session per repository or one worktree per lot, and the journal says so. In a repository with `orchestrate.worktrees: true` and a cap above 1, every lot gets its own worktree, a lot launched alone or brought by `--add` included, so a second lot of the same repository plays in parallel instead of waiting; `--dry-run --continue` now simulates the draws one by one, as the wave plays them. `cadence orchestrate --dry-run` also announces the cost in euros of each lot and of the wave beside its token budget, and the final table and `--status` show the real cost (L529, price grid `perf.prices`). `cadence release` reads the « In two lines » section of `docs/whats-new.md` the way the test does, so a line too long or a duplicate is caught before the tag (L418), and a timing test that turned red under load in a fresh clone has a wide margin (L528).
 
 **1.38.1**: `cadence spec green <lot>` now handles a lot closed at `vert: true` with no fingerprints (closed before the seal, GitHub issue #20): it replays the lot's acceptance command and, green, writes the fingerprints in a commit that cites the lot, so a later lot that amends one of its tests no longer has to be finished outside a wave (L526, `docs/orchestrate.md`). During a local task of the lead (1.38.0), `cadence deliver`, `raf move`, `cadence spec reseal` and `cadence spec green` refuse with a message that names the task and how to end it, instead of « état illisible » or an impossible `--sha` hint (L525, `docs/raf.md`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sylad/cadence",
-  "version": "1.39.0",
+  "version": "1.40.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",
@@ -37,6 +37,15 @@
     "docs/qualite.md",
     "docs/overview.md",
     "docs/whats-new.md",
+    "docs/concepts.md",
+    "docs/concepts-lot-light.svg",
+    "docs/concepts-lot-dark.svg",
+    "docs/concepts-vague-light.svg",
+    "docs/concepts-vague-dark.svg",
+    "docs/concepts-worktrees-light.svg",
+    "docs/concepts-worktrees-dark.svg",
+    "docs/concepts-livraison-light.svg",
+    "docs/concepts-livraison-dark.svg",
     "docs/fonctionnement.md",
     "docs/fonctionnement-lot-light.svg",
     "docs/fonctionnement-lot-dark.svg",

package/skills/lead/SKILL.md

@@ -64,6 +64,12 @@ not truncated) or on a net bottleneck (`⚠ goulot`): at most one improvement lo
 their place, and the human decides. Never open a lot for a micro-optimisation or for the variation of a single window.
 Without a `⚠`, the header is empty and you say nothing about perf.
 
+A line `mémoire · MEMORY.md <n> octets > seuil <s> · …` (after the worktree lines) says the `MEMORY.md` index of the parent
+folder, loaded at every turn of your session, weighs more than `memory.indexMaxBytes` (12000 bytes by default): relay it in one
+line and propose to group its dated entries under one line that points to a secondary index. Do it only after the human agrees;
+the tour only measures, it never writes the memory. A line `mémoire · MEMORY.md illisible (…)` or the error line
+`cadence.yaml · ✗ erreur : memory.indexMaxBytes …` is relayed as it is. `--json` never carries it.
+
 Then report to the human in a compact table — one row per project — and propose **three** items
 across projects, each with project, lot id and one sentence of justification: finish what is in
 progress, then drift that blocks a delivery, then ready quick wins. **Stop and wait for the priority.**