diff --git a/docs/how-to/agent-change-process.md b/docs/how-to/agent-change-process.md index c36e14d..1cc09dd 100644 --- a/docs/how-to/agent-change-process.md +++ b/docs/how-to/agent-change-process.md @@ -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.