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

8 commits

Author SHA1 Message Date
f1c2605331 Fix: switch invariant check from pre-commit to commit-msg hook
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>
2026-02-23 16:18:29 -08:00
9ec29ae7d0 Update CLAUDE.md, ai-assistance-guide, and changelog for new C2 tooling
- 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>
2026-02-23 16:12:46 -08:00
443491cb53 Add mikado-branch-invariant-check pre-commit hook
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>
2026-02-23 16:11:49 -08:00
2864d6efe4 Add branch: frontmatter support and --resume to docs-mikado
- 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>
2026-02-23 16:10:23 -08:00
ff482c2b96 Add C2 conventions: commit naming, branch naming, cold-start, finalize exception
- 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>
2026-02-23 16:08:26 -08:00
738a0c82e1 Address PR feedback: simplify invariant rule, drop 'prior chains'
- 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>
2026-02-23 15:46:55 -08:00
211902c13b Clarify Mikado Branch Invariant allows interleaved code/close cycles
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>
2026-02-23 15:36:04 -08:00
9e39087a0a Formalize C0/C1/C2 change classification process
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>
2026-02-23 15:33:18 -08:00