Git Workflow

Branching Convention

Branch names use card IDs to tie git history to KB traceability.

feature/{card_id}_{short_note}     New feature or algorithm
bugfix/{card_id}_{short_note}      Bug fix
shadow/{card_id}                   Shadow reimplementation
kb/{card_id}                       KB-only changes (cards, tex, Doxygen)
research/{topic}                   Research work (no card ID yet)

Examples

feature/S01_pivot_strategy
bugfix/N02_overflow_check
shadow/S01
kb/S01_card_update
research/adaptive_threshold

Rules

1. Card ID in branch name when a card exists. This connects git log → KB → code in one grep.
2. Short note after the card ID — 2-4 words, lowercase, underscores.
3. research/ branches have no card ID (idea cards don't have IDs yet).
4. One branch per task. Don't mix unrelated changes.

Commit Messages

{verb} {what} [{card_id}]

{optional body: why, not what}

Examples

Add pivot strategy to symbolic factorization [S01]
Fix overflow in numeric factor accumulator [N02]
Update S01 card algorithm section [S01]
Add shadow reimplementation for solve [V03]

Verbs

Verb	When
Add	New function, file, or feature
Fix	Bug fix
Update	Modify existing code or docs
Remove	Delete code, feature, or file
Refactor	Restructure without behavior change
Shadow	Shadow reimplementation

Workflow

Simple for now — no CI/CD, no automated pipelines.

1. Create branch from main
2. Work (one agent at a time, user gates)
3. Commit after each completed task
4. Code-reviewer approves → merge to main
5. QA runs on main before release

No force pushes. No rebasing published branches.