GEODE Git & PR Workflow

Apply only the stages authorized by the current request. Review or local edits do not authorize commit, push, merge, cleanup, reinstall, or runtime restart. The workflow owns development phases; this skill owns the GitFlow procedure. Read AGENTS.md for repository guardrails.

Merge Flow

Transaction	Base and head	Merge method
Feature, fix, or release preparation	fetched origin/develop → topic branch → develop	merge
Main drift	current main → the existing topic branch, before its PR merges	local merge commit, then fresh PR CI
Promotion	develop → main	merge

Never push directly to main or develop. Promotion can batch verified features; it does not itself authorize a tag, package publication, installation, or service restart. [Unreleased] may remain on main.

Don't cases

• Don't squash or rebase a PR. Both discard the reviewed head's ancestry. Use a merge commit for feature integration, synchronization, and promotion.
• Don't open a separate main -> develop or sync/* PR. Include missing main commits in the existing feature branch before integration. CI and the merge guard reject those standalone sync heads.
• Don't run an old checkout's merge guard after fetching. Fetch refreshes remote refs, not local instructions or scripts. Inspect the guard in the owned, current worktree; a stale main checkout is not the policy authority.
• Don't confuse --merge with a method guarantee. Older guards used that flag only to authorize the write and still sent merge_method=squash.
• Don't treat green CI or a merged PR as proof of preserved history. Check the result's ordered parents against the admitted base and head. An uncertain write/readback requires inspection, not retry, cleanup, or a success claim.

Worktree Allocation

Inspect git status --short --branch, git worktree list, and any .owner before editing. Continue in the correct existing worktree when available; read-only inspection does not require allocating another checkout.

For a new implementation worktree:

git fetch origin
git worktree add .claude/worktrees/<task-name> \
  -b feature/<branch-name> origin/develop

Use the host's branch prefix when specified. Record the current session and task_id=<task-name> in the gitignored .owner file using the available file editor. Do not overwrite another session's ownership record, change branches inside a worktree, or move a checkout held by another session. Fetching does not update a checked-out local develop; allocate from the remote-tracking tip.

Before the first write of independent work, whether reused or new, run uv run python scripts/check_repo_hygiene.py assert-write-workspace in that checkout. It is read-only and requires an owned .claude/worktrees/ topic checkout. On refusal, stop and allocate or assign the worktree above; do not continue writing in the current checkout.

Architecture Ledger

Ordinary tracking documents are maintained from main. Architecture-program exceptions and status transitions belong to extensibility-roadmap.md §0.3. Read that section only when the task participates in the program.

Implementation starts from origin/develop after its package-atomic claim is merged there. It preserves IN_PROGRESS; no prospective IN_DEVELOP or DONE. The roadmap-only readiness, claim, registration, reconciliation, and full-ledger audit paths use the roadmap's own prerequisites, not an extra implementation claim. Tracking-only DONE work starts from origin/main, targets main, carries no implementation; the next owned feature branch incorporates that main history before integration. Do not turn an ordinary bug or documentation fix into a new architecture program.

Pre-PR Quality Gate

Use verification-gates.md to select local checks by changed behavior and risk. scripts/preflight.sh is the existing broad local gate runner; --fast skips tests and site generation. Report skipped checks explicitly. Neither a targeted pass nor --fast proves the full suite passed, and local checks never replace required remote CI.

Reuse passing evidence while the relevant code, configuration, dependencies, and environment are unchanged. Rerun or broaden for a new change, failed check, or unresolved concern—not merely because another workflow stage was reached. Never hide exit codes with gate | tail, gate | grep -c, or check; merge.

Functional commits include their CHANGELOG.md entry and necessary user-facing documentation. Documentation-only corrections need no artificial code commit or version bump. Regenerate affected derived artifacts through their existing generators; do not hand-edit generated snapshots. Stage only in-scope paths.

PR Body Template

Use the single repository PR template. Write the title and body in Korean, keep titles under 70 characters, and assign mangowhoiscloud. Keep Summary, Why, Changes, and Verification; fill them from the actual diff against the fetched target branch and executed checks. Group related files when that is clearer than repeating one sentence per file.

Add a GAP Audit table for audit-driven work. Include design choices, compatibility, migrations, external sources, or live-test limitations only when relevant. Promotion PRs identify included PRs, the main-ancestry result, and head-specific CI; they link feature evidence instead of copying its whole report. Do not pre-check unrun gates, fabricate counts, or attribute work to a tool/model that did not do it.

Prepare a Markdown body file with the editor and pass --body-file <path> to gh pr create; a safely quoted heredoc is also valid. The transport is not a quality rule—preserve the rendered body and inspect it after creation.

gh pr create --base develop --head <topic-branch> \
  --assignee mangowhoiscloud --title "<type>: <한국어 설명>" \
  --body-file <pr-body.md>

Post-PR CI Ratchet

Before every merge, confirm the current PR head, base, mergeability, and actual required check results. Zero attached checks, an unknown result, pending work, or a failed/cancelled/timed-out/skipped/neutral required check is not green. An inapplicable inner step may skip only when explicit change detection permits it and the enclosing required check completes successfully.

gh pr checks <PR#> --watch --repo mangowhoiscloud/geode
gh pr view <PR#> --repo mangowhoiscloud/geode \
  --json headRefOid,baseRefName,mergeable,statusCheckRollup
uv run python scripts/merge_pr.py --pr <PR#>

Run these as inspected steps, not as an unconditional command chain followed by merge. Preserve command failures. Use a bounded watcher when waiting; report meaningful state changes rather than polling an unchanged failure. On failure, inspect gh run view <run-id> --log-failed, fix the actual cause, verify affected behavior, push the scoped fix, and wait for the new head's CI. Do not delete tests or suppress a security finding merely to get green.

Classify each failure before acting: CI pending (not attached or still running: wait in one bounded watcher), code defect (fix as above), or environment interference (runner outage or shared host state such as /tmp sockets or ports; a separate worktree does not isolate these). Only a code defect spends the recovery budget: 3 fix-push cycles per task. Stop earlier when the same failure signature recurs with no new evidence. On exhaustion, record the branch, head SHA, failing check, and log location, then report the task incomplete or hand it to a new session instead of looping.

The read-only merge guard requires the live repository settings allow_merge_commit=true, allow_squash_merge=false, and allow_rebase_merge=false. These GitHub repository settings also reject obsolete squash requests from other checkouts or the UI. Only an authorized operator changes them; the guard never repairs server policy itself.

The guard checks the current head and base, current PR-linked required GitHub Actions evidence (app 15368), and server protection: strict up-to-date checks, administrator enforcement and no force-push/deletion bypass. It rejects missing or ambiguous evidence rather than interpreting an empty list as green. Pages Render lint and Build are required alongside CI and both install-smoke platforms; Deploy is intentionally not a PR check. A green CI Gate alone is insufficient when Pages fails.

Once authorized, use the same guard's explicit merge mode. It rereads the snapshot immediately before the head-pinned REST request and verifies the merged PR afterward, including exactly two ordered commit parents: the verified base SHA, then the PR head SHA. Its receipt retains the returned merge SHA even when that readback is unavailable or mismatched; do not retry an uncertain write.

uv run python scripts/merge_pr.py --pr <PR#> --merge

The guard chooses merge for feature-to-develop PRs and develop-to-main promotion. It requires the current main SHA to be an ancestor of the admitted PR head and rechecks that SHA before the write. A refusal never permits an unguarded merge. Record its merge SHA and receipt. A changed head or base requires fresh verification. Never use --admin to bypass gates or gh pr merge --delete-branch inside a linked worktree: GitHub CLI may switch that checkout while deleting the local branch. The guarded cleanup below owns branch/worktree deletion.

The server settings are a live prerequisite, not a promise made by this file. If protection or merge-method policy is weakened or unavailable, stop; do not downgrade the guard to proceed. An administrator can still change repository policy itself; the guard rejects observed policy drift but does not claim tamper-proof hosting.

Concurrent-session drift & CI-trigger recovery

Serialize develop merges. After another merge, fetch and inspect the actual content, ancestry, mergeability, and CI before deciding an update is needed. Commit-count asymmetry alone does not require rebasing every waiting worktree.

For a conflicting feature PR, merge current origin/develop in its owned worktree, preserve concurrent changes, stage only resolved in-scope paths, and rerun affected checks plus required CI on the new head. Do not rewrite another session's branch. Only an authorized release changes version stamps; verify the version remains available and regenerate affected metadata after resolving it. Ordinary fixes stay under [Unreleased].

If a new PR has no checks, inspect Actions availability, applicable workflow events/path filters, and the current head's check-runs API before treating it as a missed event. An outage is not a code failure. After confirming a missed pull_request event and authorized PR operation, close/reopen once to regenerate the event, then verify new runs attached. If checks remain absent, report the specific blocker instead of repeating mutations or treating absence as success.

Integrate main before feature merge

Fetch before integrating a feature. Check main ancestry in its owned worktree:

git merge-base --is-ancestor origin/main HEAD

Compare actual content too. If main is missing, merge origin/main there before the feature PR is admitted; resolve conflicts without rewriting history, push the synchronization commit, and wait for required CI on that new head. Also incorporate current origin/develop when strict protection or concurrent feature changes require it.

Do not create a separate main -> develop or sync/* PR. An ancestor-preserving feature merge carries both the feature and prior main history into develop. The roadmap resolver trusts only canonical main evidence already in that head; the ledger validator still checks exact closure rows rather than trusting new claims merely because main is an ancestor.

Before develop -> main, fetch and confirm main is an ancestor of develop. If main moved after feature integration, return to the owned feature/update branch, integrate the new tip, and pass fresh CI before promotion. Do not bypass that proof or create a standalone synchronization transaction.

Serialize protected-branch integrations: GitHub pins the PR head, not the non-target main tip. Rechecking ancestry does not make the last window atomic.

Release Flow

Only when a release is requested, create its worktree from origin/develop, prepare version stamps and promote the changelog under geode-changelog, then merge into develop. Leave a fresh [Unreleased] heading. Incorporate main in the release branch before its feature merge, then promote develop to main with a merge commit. Release preparation does not bypass CI or add an automatic post-release backmerge; main-owned tracking may still require incorporation into the next owned feature branch.

Tags, GitHub Release, PyPI publication, and installed-version verification follow geode-distribution only when authorized. Inspect the affected workflow's actual trigger before promising deployment; do not infer publication from a merge SHA or static workflow description.

Post-Merge Cleanup

After an owned feature PR merges and the checkout is no longer needed, run the guarded command from outside the target worktree:

uv run python scripts/check_repo_hygiene.py free-merged-worktree \
  --pr <feature-pr> --worktree .claude/worktrees/<task-name>

It verifies the merged PR and final head, replays that head onto the merge's base to compare the resulting tree, checks local ancestry and remote head, requires a clean checkout, and validates .owner.task_id. It then removes the remote branch, worktree, and local topic branch and prunes. The owner record's task-name check is not proof that another active session has released the checkout; confirm current session ownership first. Use --dry-run when inspection is needed. A refusal requires investigation, never manual force.

After promotion, verify fetched branch content and the actual requested CI or deployment result. Reuse unchanged docs/test evidence; investigate drift if the merged result differs. Update tracking only when in scope, through its owning workflow. Report PRs, merge SHAs, verification, skipped work, and cleanup results.

Rebuild & Restart

A merge does not authorize changing global installations or running services. When deployment or restart is explicitly in scope:

1. Resolve the intended installation, checkout, process identity, and owner. Inspect core/cli/commands/lifecycle.py before selecting the operation; a process-name match alone does not establish ownership.
2. Stop only the confirmed in-scope process. Do not use broad pkill -f, stop another session, or hide a failed stop with || true.
3. Install the requested channel and extras under the distribution contract. Editable global installation and [audit] are not ordinary runtime defaults.
4. Verify version, process identity, and the requested smoke result. If ownership or restart authority is unclear, preserve the artifact and ask for direction.