GEODE Git & PR Workflow

Merge Flow (mandatory)

feature → develop → main order. Direct push to main prohibited — must go through PR.

feature/xxx ──PR──→ develop ──PR──→ main

Full Workflow

Principle 1: Every work unit starts with worktree open (alloc) and ends with worktree close (free). No direct git checkout feature/* in the main repo. No exceptions.

Principle 2: develop merge uses a queue approach — one at a time. Rebase next worktree after merge.

0.  ★ Frontier Research (for new infrastructure features)
    DISCOVER → COMPARE → DECIDE → DOCUMENT
1.  worktree open + feature branch creation  ← alloc
2.  Code changes (within worktree)
3.  ★ Pre-PR Quality Gate (iterate)
4.  Commit (code + docs together)
5.  PR creation (feature → develop)
6.  ★★ Post-PR CI Ratchet (mandatory)
7.  merge (feature → develop)            ← queue: one at a time
8.  develop → main PR creation (batchable)
9.  ★★ Post-PR CI Ratchet (mandatory)
10. merge (develop → main)
11. ★★★ Docs-Sync Final Verification
12. worktree close + branch deletion          ← free

Step 0 applicability: Mandatory for new infrastructure features (Gap, architecture changes). Can be skipped for simple bug fixes, documentation updates, or repeating existing patterns.

Develop Merge Queue (when running parallel worktrees)

When multiple worktrees are open simultaneously, manage develop merges as a sequential queue.

Worktree A (fix/xxx)  ──→ PR → CI pass → merge #1 ──┐
                                                      │ develop updated
Worktree B (fix/yyy)  ──→ PR → CI pass ──→ rebase ──→ merge #2 ──┐
                                                                   │
Worktree C (fix/zzz)  ──→ PR → CI pass ──→ rebase ──→ merge #3 ──┘
                                                                   │
                                              develop → main PR (batch)

Queue rules:

• Only one merge to develop at a time (conflict prevention)
• After merge, next waiting worktree rebases onto develop then pushes
• Re-run CI after merge (code changed due to rebase)
• develop → main can batch multiple features

bash
1# Queue order management — rebase next worktree
2cd .claude/worktrees/<next-task-name>
3git fetch origin develop
4git rebase origin/develop
5git push --force-with-lease
6# → CI re-triggered → confirm pass → merge

Step 0: ★ Frontier Research (mandatory pre-implementation research)

Applicability: Mandatory for new infrastructure features (Gap, architecture changes). Can skip for simple bug fixes.

Investigate implementations in frontier harnesses (Claude Code, Codex CLI, OpenClaw, Aider, autoresearch, etc.), create a comparison matrix, and document design decisions.

DISCOVER (investigate harnesses via parallel Agents)
  → COMPARE (feature × harness matrix)
  → DECIDE (Option A/B/C + selection rationale)
  → DOCUMENT (docs/plans/research-<topic>.md)

Open source (Codex, Aider, autoresearch, OpenClaw) — verify source directly via gh api. Closed source (Claude Code only) — official docs/secondary sources — state verification limitations.

Step 1: Worktree Open (alloc)

Every work unit starts by opening a worktree. No exceptions.

bash
1# 0. Sync verification gate (CANNOT rule — never skip)
2git fetch origin
3
4LOCAL_MAIN=$(git rev-parse main)
5REMOTE_MAIN=$(git rev-parse origin/main)
6[ "$LOCAL_MAIN" != "$REMOTE_MAIN" ] && echo "STOP: local main ≠ origin/main" && git checkout main && git pull origin main
7
8LOCAL_DEV=$(git rev-parse develop)
9REMOTE_DEV=$(git rev-parse origin/develop)
10[ "$LOCAL_DEV" != "$REMOTE_DEV" ] && echo "STOP: local develop ≠ origin/develop" && git checkout develop && git pull origin develop
11
12# 1. Create worktree = allocate workspace (based on develop)
13git worktree add .claude/worktrees/<task-name> -b feature/<branch-name> develop
14
15# 2. Move to work directory
16cd .claude/worktrees/<task-name>
17
18# → Steps 2~11 all performed within this worktree

Worktree rules:

• .claude/worktrees/ is in .gitignore
• No git checkout within worktree (HEAD conflict)
• No git checkout feature/* in main repo — access only via worktree
• Leak check: git worktree list to find unclosed worktrees

★ Pre-PR Quality Gate (mandatory loop before commit)

After code changes, this loop must pass before commit/PR.

Code changes complete
   │
   ▼
┌─────────────────────────────────────────┐
│  Step 1: CI Guardrails (all must pass)  │
│                                         │
│  uv run ruff check core/ tests/         │ → On fail: ruff --fix then re-run
│  uv run ruff format --check core/ tests/│ → On fail: ruff format then re-run
│  uv run mypy core/                      │ → On fail: fix types then re-run
│  uv run bandit -r core/ -c pyproject.toml│ → On fail: fix security then re-run
│  uv run pytest tests/ -m "not live" -q  │ → On fail: fix tests then re-run
│                                         │
│  Any failure → fix → re-run Step 1      │
│                                         │
│  ※ Detailed inspection lenses:          │
│    code-review-workflow                  │
│    (structure/deps/security/migration/   │
│     performance)                         │
└────────────────┬────────────────────────┘
                 │ All passed
                 ▼
┌─────────────────────────────────────────┐
│  Step 2: Docs Writing (mandatory on     │
│  code changes)                          │
│                                         │
│  □ Add entry to CHANGELOG.md            │
│    [Unreleased]                         │
│    - Added / Changed / Fixed / Removed  │
│    - Can skip if no code changes        │
│                                         │
│  □ Sync CLAUDE.md metrics (if changed)  │
│    - When Tests, Modules change         │
│                                         │
│  □ Update docs/progress.md today's      │
│    date section                         │
│    - Completion table + remaining table  │
│                                         │
│  Omission found → fix → re-run Step 1   │
└────────────────┬────────────────────────┘
                 │ All complete
                 ▼
┌─────────────────────────────────────────┐
│  Step 3: Commit                         │
│                                         │
│  Include code + docs in a single commit │
│  No separate docs-only commits          │
│  (maintain consistency)                 │
│                                         │
│  git add <code files> CHANGELOG.md ...  │
│  git commit -m "<type>: <description>"  │
└────────────────┬────────────────────────┘
                 │
                 ▼
           Ready to create PR

Quality Gate Anti-patterns

★★ Post-PR CI Ratchet — Mandatory Before Merge (CRITICAL)

Karpathy P4: Ratchet = advance only on verification pass, rollback on failure. Merging a PR without CI green is a ratchet violation.

Absolute Rule

Before running gh pr merge, you must check CI status with gh pr checks. Merge prohibited if CI is still running or has failed.

Merge Ratchet Loop

PR creation complete
   │
   ▼
┌──────────────────────────────────────────────────┐
│  Step A: Wait for CI completion + check results   │
│                                                   │
│  gh pr checks <PR#> --watch --repo <owner/repo>   │
│                                                   │
│  → All pass  → Proceed to Step B                  │
│  → Any fail → Proceed to Step C                   │
│  → pending/running → Wait (--watch auto-waits)    │
└────────────────┬──────────────────────────────────┘
                 │
        ┌────────┴────────┐
        ▼                 ▼
┌──────────────┐  ┌──────────────────────────────┐
│  Step B:     │  │  Step C: Failure fix loop      │
│  Run Merge   │  │                                │
│              │  │  1. gh run view --log-failed    │
│  gh pr merge │  │     → Identify failure cause    │
│  <PR#>       │  │  2. Fix locally                 │
│  --merge     │  │  3. Commit + push (same branch) │
│              │  │  4. CI auto re-triggered         │
│              │  │  5. Return to Step A             │
│              │  │                                  │
│              │  │  (Repeat until pass)             │
└──────────────┘  └──────────────────────────────────┘

Merge Command Template (copy and use)

bash
1# ── feature → develop ──
2
3# 1. Create PR
4gh pr create --base develop --assignee mangowhoiscloud \
5  --title "<type>: <description>" \
6  --body "<detailed body template>"
7
8# 2. ★★ CI Ratchet: Wait for checks to pass (MUST — never skip)
9gh pr checks <PR#> --watch --repo mangowhoiscloud/geode
10
11# 3. Merge only after all pass
12gh pr merge <PR#> --merge --repo mangowhoiscloud/geode
13
14# ── develop → main ──
15
16# 4. Create PR
17gh pr create --base main --head develop --assignee mangowhoiscloud \
18  --title "<type>: <description> (develop → main)" \
19  --body "<develop → main template>"
20
21# 5. ★★ CI Ratchet: Wait for checks to pass (MUST — never skip)
22gh pr checks <PR#> --watch --repo mangowhoiscloud/geode
23
24# 6. Merge only after all pass
25gh pr merge <PR#> --merge --repo mangowhoiscloud/geode

CI Failure Fix Loop

bash
1# Check failure logs
2gh pr checks <PR#> --repo mangowhoiscloud/geode
3gh run view <run_id> --log-failed
4
5# Fix locally → push → CI auto re-runs
6# ... fix ...
7git add -A && git commit -m "fix: <CI failure cause fix>"
8git push
9
10# Check ratchet again
11gh pr checks <PR#> --watch --repo mangowhoiscloud/geode
12# pass → merge

Common CI Failure Causes and Responses

PR Writing Rules

★ PR Body Build Rules (CRITICAL — must follow)

A weak PR body prevents reviewers from understanding the change intent. A 1-3 line PR body is an anti-pattern. Fill all required sections from the template below.

Before generating PR body, you must:

1. Check full diff with git diff develop...HEAD
2. Classify all changed files into core/secondary/docs
3. Write a one-line why rationale for each file change
4. Copy test result numbers from actual execution output (no XXXX placeholders)
5. Use HEREDOC format (prevents line break/markdown breakage)

Anti-pattern vs Correct PR Body

PR Body Detailed Template (feature → develop)

All sections are required. If not applicable, state "N/A".

markdown
1## Summary
2<!-- Required. 2-3 lines. "What" + "why" changed. Include background motivation. -->
3
4<Core of the change in 2-3 sentences. What problem existed and how this PR solves it.>
5
6## Changes
7
8### Core Changes (Code)
9<!-- Required. List all changed files without omission. -->
10- `filepath:line-range`: Change content — AS-IS → TO-BE
11  - Rationale: One-line explanation of why this change was made
12
13### Secondary Changes (Code)
14<!-- If N/A, state "None" -->
15- `filepath`: Rename/format/type fixes etc.
16
17### Documentation/Config Changes
18<!-- Required. If code changed, CHANGELOG must be included. -->
19- `CHANGELOG.md`: Items added to [Unreleased] > Fixed/Added/Changed
20- `CLAUDE.md`: Updated items (if applicable)
21- `pyproject.toml`: Dependency/config changes (if applicable)
22
23## Impact Scope
24<!-- Required. -->
25- **Affected modules**: <specific paths like core/cli, core/ui>
26- **Backward compatibility**: Maintained / Broken (if broken, attach migration guide)
27- **Test changes**: Added N / Modified N / Deleted N
28
29## Design Decisions
30<!-- Required for structural changes. For simple bug fixes, state "Simple fix, no design decisions needed." -->
31- Why was approach B chosen over approach A?
32- If referencing frontier harness cases: link `docs/plans/research-<topic>.md`
33- Alternative comparison: Option A (pros/cons) vs Option B (pros/cons) → selection rationale
34
35## Pre-PR Quality Gate (required — paste actual execution results)
36- [x] `ruff check` — 0 errors
37- [x] `ruff format --check` — OK (N files)
38- [x] `mypy core/` — Success (N source files)
39- [x] `bandit -r core/` — 0 issues
40- [x] `pytest -m "not live"` — **N passed** in Xs
41- [x] CHANGELOG.md [Unreleased] entry added
42- [x] README.md metric consistency verified
43- [ ] CLAUDE.md sync (if applicable)
44- [x] docs/progress.md today's date section updated
45
46🤖 Generated with [Claude Code](https://claude.com/claude-code)

PR Body Template (develop → main)

markdown
1## Summary
2develop → main merge. <1-2 line summary of main changes. What features/fixes are included.>
3
4## Included Changes
5<!-- Required. List all feature PRs with numbers and titles. -->
6- #number `<type>: <title>` — One-line summary of core change
7- #number `<type>: <title>` — One-line summary of core change
8
9## Change Metrics
10- **Files**: N files changed
11- **Tests**: N passed (compared to previous +N/-N)
12- **Modules**: N (specify if changed)
13
14## Testing
15- [x] Full CI passed (`gh pr checks --watch` confirmed)
16- [x] feature → develop CI pass confirmed
17
18🤖 Generated with [Claude Code](https://claude.com/claude-code)

gh pr create Command — HEREDOC Required

PR body must be passed in HEREDOC format. Inline --body "..." prohibited.

bash
1# ✅ Correct: HEREDOC
2gh pr create --base develop --assignee mangowhoiscloud \
3  --title "<type>: <description>" \
4  --body "$(cat <<'PRBODY'
5## Summary
6...fill full template...
7
8🤖 Generated with [Claude Code](https://claude.com/claude-code)
9PRBODY
10)"
11
12# ❌ Prohibited: Inline (line breaks broken, content truncated)
13gh pr create --body "One line summary"

★★★ Docs-Sync Final Verification (after main merge, before cleanup)

Performed after the work unit is fully merged to main. Even if docs were written in Pre-PR Step 2, metrics may change during the merge process, so final verification is needed.

Verification Checklist

main merge complete (step 10)
   │
   ▼
┌──────────────────────────────────────────────────┐
│  □ README.md metric consistency                   │
│    - modules: find core/ -name "*.py" | wc -l     │
│    - tests: uv run pytest --co 2>&1 | wc -l       │
│    - tools count, version                         │
│                                                   │
│  □ CLAUDE.md metric consistency                   │
│    - Verify Tests, Modules using same criteria    │
│                                                   │
│  □ CHANGELOG.md [Unreleased] omission check       │
│    - Are changes merged to main recorded?         │
│                                                   │
│  □ docs/progress.md today's date section exists   │
│    - If missing, add and commit                   │
│                                                   │
│  □ pyproject.toml coverage omit                   │
│    - Check if new module is in omit breaking      │
│      coverage                                     │
│                                                   │
│  → If mismatch found:                             │
│    docs(sync) commit → feature → develop → main   │
│    (apply same gitflow loop)                      │
│  → If no issues: proceed to step 12               │
│    (workspace cleanup)                            │
└──────────────────────────────────────────────────┘

Pre-PR Step 2 vs Docs-Sync Final Verification

Docs are written in Pre-PR, and the final verification after main merge catches anything missed — a dual-layer structure.

Branch Structure

main ─────────────────────────── production (stable, tagged)
  │
  └── develop ────────────────── integration (CI mandatory)
        │
        ├── feature/<name> ───── Feature development
        ├── hotfix/<name> ────── Emergency fixes (branch from main)
        └── release/v<semver> ── Release preparation

Commit Convention

<type>(<scope>): <description>

Types: feat, fix, refactor, test, docs, ci, chore
Scopes: pipeline, scoring, analysis, verification, cli, memory, tools, llm

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

CI Pipeline (GitHub Actions)

lint ─────┐
typecheck ─┤
test ──────┼──→ gate (all must pass for merge)
security ──┘

bash
1# Local CI guardrails (Pre-PR)
2uv run ruff check core/ tests/
3uv run ruff format --check core/ tests/
4uv run mypy core/
5uv run bandit -r core/ -c pyproject.toml
6uv run pytest tests/ -m "not live" -q
7
8# GitHub CI ratchet (Post-PR, mandatory before merge)
9gh pr checks <PR#> --watch --repo mangowhoiscloud/geode

Step 12: Worktree Close (free)

After merge completion, worktree must be closed. No exceptions.

bash
1# 1. Return to main repo
2cd /Users/mango/workspace/geode
3
4# 2. Update develop/main to latest
5git checkout develop && git pull origin develop
6
7# 3. Remove worktree = release workspace
8git worktree remove .claude/worktrees/<task-name>
9
10# 4. Branch cleanup (local + remote)
11git branch -d feature/<branch-name>
12git push origin --delete feature/<branch-name>
13
14# 5. Leak check
15git worktree list   # No unclosed worktrees should remain

Local Merge (exception when PR creation impossible)

Only use local merge when PR creation is impossible (e.g., GitHub "No commits between" error):

bash
1git stash
2git checkout develop && git merge feature/<name> --no-edit && git push origin develop
3git checkout main && git merge develop --no-edit && git push origin main
4git checkout feature/<name> && git stash pop