eblume/blumeops
1
1
Fork 0
Code Issues Pull requests Projects Releases 83 Packages Wiki Activity Actions

Clarify Mikado Branch Invariant allows interleaved code/close cycles

Browse source 
The work phase after the card layer is a repeating cycle of
(code → close leaf), not a single block of all code followed by
all closures.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Erich Blume 2026-02-23 15:36:04 -08:00
commit 211902c13b
1 changed files with 8 additions and 8 deletions
Download patch file Download diff file Expand all files Collapse all files

16
docs/how-to/agent-change-process.md
View file

@ -71,22 +71,22 @@ A complex, multi-session change managed through the [Mikado method](https://mika
The invariant governs how commits are ordered on a C2 feature branch. The branch must always have this structure:
```
main ← [Mikado card commits] ← [code commits] ← [card-closing commits]
^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^
Planning layer Implementation Resolution
(cards only) (code only) (close leaf nodes)
main ← [card commits] ← [code, close] ← [code, close] ← ... ← [finalize]
^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Planning layer Repeating work cycles
(cards only) (code then close, one leaf at a time)
```
**Rules:**
1. The first N commits on the branch (after diverging from main) must ALL be commits that **only introduce or modify Mikado cards** — no code changes
2. After the card commits, a series of commits (preferably just one) make **code progress toward closing a leaf node** — these commits must NOT introduce or change Mikado cards
3. The code commits must be followed by one or more commits that **close Mikado leaf nodes** based on the work done
4. This pattern (code → close) repeats until the chain is complete
2. After the card layer, work proceeds in **cycles**: each cycle is one or more code commits followed by one or more commits closing leaf nodes
3. A cycle should target a single leaf node (though closing multiple in one cycle is acceptable if the code supports it)
4. Cycles repeat until the chain is complete
**What is NOT allowed:**
- Introducing a Mikado card in a commit that comes after code progress commits
- Introducing a new Mikado card after any code or card-closing commit (new cards require a branch reset — see below)
- Closing a Mikado card before all cards it depends on have been introduced
**The length-zero case:** It is valid for the "planning layer" to have zero commits on the branch — this happens when all Mikado cards were introduced in earlier sessions and are already in main's history. The invariant is satisfied.