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

Formalize C0/C1/C2 change classification #259

Merged
eblume merged 8 commits from formalize-change-classification into main 2026-02-23 16:19:54 -08:00
Conversation 1 Commits 8 Files changed 8 +728 -68
eblume commented 2026-02-23 15:33:53 -08:00
Owner
Copy link

Summary

  • C0 (Quick Fix): Now explicitly allows direct-to-main commits with no PR required — for low-risk, fix-forward-safe changes
  • C1 (Human Review): New docs-first workflow with branch deployment (ArgoCD --revision, Ansible from checkout). Includes upgrade criteria for escalation to C2
  • C2 (Mikado Chain): Introduces the Mikado Branch Invariant — strict commit ordering where card-introducing commits come first, followed by code progress, followed by card closures. Branch resets required when new prerequisites are discovered

Updates CLAUDE.md rules (3, 4, 8, 9) to reflect that C0 bypasses branching/PR requirements. Also updates ai-assistance-guide, how-to index, and docs-mikado task description.

Files changed

  • CLAUDE.md — rules and classification table
  • docs/how-to/agent-change-process.md — full process rewrite
  • docs/tutorials/ai-assistance-guide.md — branching and pitfalls sections
  • docs/how-to/how-to.md — index description
  • mise-tasks/docs-mikado — task description
  • docs/changelog.d/formalize-change-classification.doc.md — changelog fragment
## Summary - **C0 (Quick Fix):** Now explicitly allows direct-to-main commits with no PR required — for low-risk, fix-forward-safe changes - **C1 (Human Review):** New docs-first workflow with branch deployment (ArgoCD `--revision`, Ansible from checkout). Includes upgrade criteria for escalation to C2 - **C2 (Mikado Chain):** Introduces the **Mikado Branch Invariant** — strict commit ordering where card-introducing commits come first, followed by code progress, followed by card closures. Branch resets required when new prerequisites are discovered Updates CLAUDE.md rules (3, 4, 8, 9) to reflect that C0 bypasses branching/PR requirements. Also updates ai-assistance-guide, how-to index, and docs-mikado task description. ## Files changed - `CLAUDE.md` — rules and classification table - `docs/how-to/agent-change-process.md` — full process rewrite - `docs/tutorials/ai-assistance-guide.md` — branching and pitfalls sections - `docs/how-to/how-to.md` — index description - `mise-tasks/docs-mikado` — task description - `docs/changelog.d/formalize-change-classification.doc.md` — changelog fragment
Redefine the three change classes with clearer boundaries:
- C0: direct-to-main commits for low-risk, fix-forward-safe changes
- C1: feature branch + PR with docs-first workflow and branch deployment
- C2: Mikado Branch Invariant enforcing strict commit ordering (card
  commits first, code progress, card closures) with branch resets on
  new prerequisite discovery

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
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>
eblume reviewed 2026-02-23 15:45:58 -08:00
docs/how-to/agent-change-process.md Outdated
@ -50,0 +42,4 @@
### Process
1. Run `mise run ai-docs` to load context
2. **Search related docs** — read existing documentation, reference cards, and prior Mikado chains related to the change area
eblume commented 2026-02-23 15:39:26 -08:00
Author
Owner
Copy link

You don't need to call out "prior Mikado chains". When a mikado chain is done, it just becomes... documentation. That's a crucial point, mikado chains are for active in-progress work. When they are done, what's left is the resulting code and a set of docs that might possibly be useful in the future for repeating the process in part or whole.

You don't need to call out "prior Mikado chains". When a mikado chain is done, it just becomes... documentation. That's a crucial point, mikado chains are for active in-progress work. When they are done, what's left is the resulting code and a set of docs that might possibly be useful in the future for repeating the process in part or whole.
eblume marked this conversation as resolved
docs/how-to/agent-change-process.md
@ -50,0 +87,4 @@
**What is NOT allowed:**
- 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
eblume commented 2026-02-23 15:42:09 -08:00
Author
Owner
Copy link

honestly this feels like a weaker version of the previous rule, no? Let's think about how we can express this invariant as succinctly as possible. It occurs to me that there's another possibility we haven't precluded, which is a commit that closes a mikado leaf node PRIOR to the code which resolves that leaf node. This would imply that we closed a leaf node that wasn't actually done. Not sure it needs to be called out... the rule is just "don't close mikado leaf nodes that aren't done" I guess? Probably not worth calling out.

honestly this feels like a weaker version of the previous rule, no? Let's think about how we can express this invariant as succinctly as possible. It occurs to me that there's another possibility we haven't precluded, which is a commit that closes a mikado leaf node PRIOR to the code which resolves that leaf node. This would imply that we closed a leaf node that wasn't actually done. Not sure it needs to be called out... the rule is just "don't close mikado leaf nodes that aren't done" I guess? Probably not worth calling out.
eblume marked this conversation as resolved 
- Remove "prior Mikado chains" from C1 doc search step — completed
  chains are just documentation, not a special category
- Collapse the two "not allowed" bullets into a single rule: no card
  may be introduced after any code or card-closing commit

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Commit convention: C2(<chain>): plan/impl/close/finalize <description>
- Branch convention: mikado/<chain-stem>
- Goal card branch: frontmatter linking chain to branch
- Planning/research phase documented as first step of C2
- Cold-start session guidance via docs-mikado --resume
- Finalize as explicit exception to the one rule
- Verification happens on impl commits before closing leaf nodes
- Document planned tooling (docs-mikado --resume, mikado-branch-invariant-check)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Parse branch: field from goal card frontmatter
- Goal cards without branch: shown as "not started" (planned but no branch)
- Add Branch column to chain listing table
- New --resume flag for cold-start session pickup:
  - Detects current mikado/* branch and matches to active chain
  - Shows branch position (planning/mid-cycle/between-cycles) by parsing
    C2() commit convention from git log
  - Lists ready leaf nodes for next work cycle
  - With explicit chain name, validates branch consistency
  - On main, lists all chains with branch status and ready leaves
- Add find_ready_leaves() helper for identifying actionable leaf nodes
- Add C2_COMMIT_RE for parsing C2(<chain>): <verb> <desc> convention
- Show branch: in walk_chain card detail output

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Validates the Mikado Branch Invariant on mikado/* branches:
- All commits must follow C2(<chain>): <verb> <description> convention
- plan commits must precede all impl/close commits
- close commits must follow impl commits
- finalize must be the last commit
- Chain stem in commit messages must match branch name

Silently passes on non-mikado branches (exit 0).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- CLAUDE.md: add branch naming, commit convention, and --resume to C2 summary
- ai-assistance-guide: add docs-mikado --resume to mise tasks table
- Changelog fragment: cover all new conventions and tooling

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The pre-commit stage runs before the commit is created, so it can't
validate the commit being made. The commit-msg stage receives the
message file as argv[1], allowing the hook to include the pending
commit in its invariant check.

Also works standalone (no args) for validating existing branch history.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
eblume merged commit 66b5b32f1d into main 2026-02-23 16:19:54 -08:00
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
eblume/blumeops!259
No description provided.