git-discipline

name	git-discipline
description	Run BEFORE any git write (commit, push, merge) and before a stale checkout or branch read: exists? landed? — in this multi-agent repo the filesystem answers for someone else's branch, not yours, so `git show origin/main:<path>` is the only honest answer to "does X exist / did Y land". (Trigger note: this index derives keywords from the FIRST 12 non-stopword tokens of this description — `_triggers_from_text(limit=12)` — so the read-side terms above MUST stay in this opening sentence; when they weren't, this skill could only fire on writes while the trap fires on a READ, and it took three victims in one hour.) The full write surface still applies: commit, push, branch, switch, rebase, merge, open/close/merge a PR, re-trigger CI, "unblock #NNN", or diagnose a failing CI check, a "superseded/divergent" branch, or a "CI seems stuck" / green-but-won't-merge PR (decode mergeable_state FIRST — see §3a), a DIRTY/CONFLICTING mergeable_state stuck on a stale GitHub cache even when merge-base --is-ancestor + merge-tree prove 0 conflicts (base-toggle to force a recompute — see §3a-i), a stuck-DIRTY PR whose required pull_request checks never fire because GitHub won't build refs/pull/N/merge (advance the branch + base-toggle to rebuild the merge ref — see §3a-ii), or a recurring add/add conflict on a file two PRs both created (a dispatch-plan / evidence artifact under agi-proof — see §4b). This repo (tomyimkc/sophia-agi) has many concurrent advisors (Claude/Copilot/GLM/human) on many worktrees pushing to main around the clock, so a local checkout is a STALE snapshot the moment it is taken. Use even if the conversation already contains a diagnosis or a "you are on branch X" line — that may be stale.
metadata	{"short-description":"Stale-snapshot / merge-blocker / verify-before-act discipline for this high-churn repo"}

Git & merge discipline (this repo)

See also spark-cluster-ops §3-4 for the cluster addenda: the git-crypt worktree/cherry-pick -c bypass, the failed-worktree add collision recovery (branch -f → reset --hard), and shared-branch rebase reconcile.

This repo has many concurrent advisors pushing and merging to main constantly. Every expensive mistake here came from acting on an unverified local picture: a fix PR built off main that was 28 commits behind; a duplicate PR for a problem another advisor already fixed; a "merge" blocked by unresolved review threads (not CI); a cancelled CI run misread as a real failure. This skill is the cheap pre-flight that prevents that whole class of waste.

The canonical, fuller playbooks + ready-to-run scripts live in .agents/skills/ (shared with the other agent tools). This skill is the Claude-Code entry point — it routes you to them and states the rules. Do not re-implement the scripts; call them.

1. Before ANY git write — situational awareness (1 s, read-only)

python .agents/skills/git-operations/scripts/git_situational_awareness.py        # human
python .agents/skills/git-operations/scripts/git_situational_awareness.py --json # machine

Exit code is the verdict: 0 safe · 1 warnings (review, then proceed) · 2 blockers (stop). It answers the six questions: where am I, is a sibling worktree on this branch, what's uncommitted, am I stale vs origin/main, is there a competing PR on this branch, is main directly pushable. It does not fetch — run git fetch origin --prune first when you need fresh remote truth.

2. Before any merge / unblock / CI-fix — merge pre-flight

git fetch origin --prune
python .agents/skills/multi-agent-merge-preflight/scripts/merge_blockers.py NNN

Re-verify the thing is still broken on origin/main (another advisor may have fixed it), check for a competing PR before opening your own, and enumerate all merge blockers — not just CI. The silent killer here is required_review_thread_resolution: true: green checks but unresolved review threads still block the merge.

3. Verify before you act (the three false calls that happened here)

• "Divergent/superseded" by line count → wrong. Test ancestry + a trial merge, never line counts.
• "test: fail" → may be a cancelled run (job conclusion cancelled, not failure) caused by main moving mid-run. Read the job conclusion and re-trigger before "fixing" a ghost.
• A "bug" in a PR → reproduce it on the PR's current head against fresh origin/main first.

Full reasoning + the exact gh api graphql thread-resolution recipe: .agents/skills/pr-merge-verification/SKILL.md and .agents/skills/multi-agent-merge-preflight/SKILL.md.

3a. "CI seems stuck" — decode mergeable_state before touching anything (2026-07-06, PR #681)

A PR whose check-runs are ALL green can still sit unmergeable for hours and read as "stuck CI". The check list is the wrong place to look — fetch the PR object and branch on mergeable_state:

mergeable_state	It means	The move
dirty	main moved and now conflicts with the PR (typical cause here: a squash-merge of a sibling PR carrying overlapping history)	freeze-check (live-evidence-branch-freeze), then git fetch origin main && git rebase origin/main — already-squash-merged commits drop out on their own — then push --force-with-lease. Rebase, don't merge-commit: the ruleset requires linear history
behind	main moved, no conflict	update branch / rebase, same freeze-check first
blocked	a protection rule is unsatisfied: checks still running on the new head, or required_review_thread_resolution (green checks + unresolved threads)	wait for checks / resolve threads — NOT an error, do not re-kick CI
unstable	a non-required check failed	read which; required ones may still be green
unknown	GitHub is still computing	re-fetch in ~10 s, don't act on it

Two traps measured in this repo: (1) rebasing flips dirty → blocked, which looks like a new problem but just means the checks are re-running on the new head; (2) a run shown "failed" on the old head after your push is usually cancelled (superseded), per §3.

3a-i. Stale-cache DIRTY that base-toggle clears (2026-07 sessions, #932 wave)

The table row for dirty assumes the conflict is real. The 2026-07 merge wave hit a second shape: a PR you have proven clean — git merge-base --is-ancestor origin/main HEAD succeeds AND git merge-tree $(git merge-base origin/main HEAD) origin/main HEAD prints zero conflict markers — still reads mergeable: CONFLICTING / mergeStateStatus: DIRTY on GitHub for hours or days. That is a stale server-side mergeability cache, not a conflict (the full reasoning and the admin-merge escape hatch are in §4b's "Stale mergeability cache" paragraph). Before reaching for gh pr merge --squash --admin, try the lighter move that forces GitHub to recompute from scratch:

(a) Base-toggle. Flip the PR base to a throwaway branch and back. A base change invalidates the cached mergeable_state, so GitHub runs a full recompute on the restore:

BASE=$(gh pr view NNN --json baseRefName -q .baseRefName)          # capture the real base, e.g. main
git push origin origin/main:refs/heads/zzz-stale-cache-recompute   # temp base MUST be a real branch — create it first
gh pr edit NNN --base zzz-stale-cache-recompute                    # flip base → invalidates the cached mergeable_state
gh pr edit NNN --base "$BASE"                                      # restore — mergeable_state recomputes here
gh pr view NNN --json mergeable,mergeStateStatus                   # re-read; DIRTY → CLEAN within ~1 min
git push origin :refs/heads/zzz-stale-cache-recompute             # clean up the throwaway branch

Use gh pr edit --base (it PATCHes the pulls endpoint under the hood); the raw-REST equivalent is gh api -X PATCH repos/tomyimkc/sophia-agi/pulls/NNN -f base=… — not the issues/NNN endpoint, which shares the number but silently ignores a base field and no-ops. GitHub requires a PR's base to be an existing branch ref (a non-existent base is rejected 422), so the throwaway target is created before the toggle (the git push origin origin/main:refs/heads/… line above) and deleted after. An empty commit, a real commit, and close/reopen have all been observed to fail to clear this cache; the base-toggle is the reliable nudge short of --admin. Re-confirm ancestry first (--is-ancestor still succeeds) — if it now fails, a sibling has landed a real overlapping change and the DIRTY is genuine: rebase, do not toggle over it.

3a-ii. DIRTY that starves pull_request CI — rebuild the merge ref (2026-07 sessions)

A worse corollary: when mergeable_state is stuck DIRTY, GitHub may refuse to build refs/pull/N/merge — the ref your pull_request / pull_request_target workflows run against. Symptom: the PR shows no check runs at all (or only the always-on schedule/push ones), the required checks fast + ci-complete never fire, and the PR can never become mergeable on its own — it isn't failing CI, it's being starved of CI. Do not read an empty check list as "checks haven't reported yet"; read it as "the merge ref was never built".

The fix is to rebuild the merge ref, in this order:

1. Advance the branch — push a trivial commit (git commit --allow-empty -m "chore: retrigger CI — merge ref stuck" and push) so GitHub cuts a fresh head and, with it, a fresh refs/pull/N/merge.
2. Base-toggle (§3a-i) — if advancing alone doesn't rebuild the merge ref, the stale-cache DIRTY is the cause; the base-toggle forces the recompute that also recreates the merge ref.
3. Re-read: gh pr view NNN --json mergeable,statusCheckRollup — the required checks should now schedule and run against the restored merge ref.

Distinguish from the benign cases before acting: a genuinely blocked PR (checks still running) and a behind PR (main moved, no conflict) both show check runs in progress — only a stuck-DIRTY PR shows the required checks absent. If --is-ancestor succeeds and merge-tree is clean, the absent checks are the cache, not your code.

No gh CLI (remote/web containers): merge_blockers.py and the §5 recipes die with FileNotFoundError: 'gh'. Do the same checks via the GitHub MCP tools (pull_request_read: get for mergeable_state, get_review_comments for unresolved threads, get_check_runs) or plain unauthenticated REST — this repo is public: curl -s https://api.github.com/repos/tomyimkc/sophia-agi/pulls/NNN | jq .mergeable_state (rate limit 60/hr/IP — poll at ≥60 s and tolerate empty responses).

4. When you commit, isolate your changes

The working tree is frequently contaminated by other advisors' uncommitted work.

• git add <explicit file list> — never git add -A / git add ..
• git diff --cached --stat to confirm only your files are staged.
• Confirm git branch --show-current and git log --oneline -1 before pushing.
• Develop on the branch the user named; direct pushes to main are blocked by protection.
• Gitignored generated paths need git add -f — this has bitten 3× (2026-07-06). .claude/skills/, training/worldmodel/, skills/portable/ are gitignored, yet they hold tracked-and-committed files (skills) or files a lane must deliver (fresh corpora). A plain git add <gitignored-path> is silently refused ("Use -f if you really want to add them") → an empty commit → the push "succeeds" with nothing, or a results-branch delivery step exits 1 after the expensive work already ran (corpus run 28799005486 spent both teacher fleets, then the git add training/worldmodel/... in its push step was refused and the branch delivery failed — data survived only because a second artifact channel existed). Any lane or commit touching a gitignored path uses git add -f, and a results-branch delivery step must fail LOUD if the commit is empty (git diff --cached --quiet && { echo '::error::nothing staged'; exit 1; }).

4a. NEVER git stash in this repo — the stash stack is shared across worktrees

The stash is per-repository, not per-worktree: every worktree that shares the .git dir sees the SAME git stash list. Two ways this bites (both happened here):

• git stash push -- <pathspec> where a path is untracked aborts with "Did you forget to 'git add'?" and creates no stash — but a script that then runs git stash pop pops the top of the shared stack, which belongs to another session, dumping their WIP (and merge conflicts) into your worktree.
• Even a successful stash can be popped by a different worktree's session.

Instead of stashing to get a clean tree for a quick test: don't — you already have an isolated worktree; run the test with your changes in place, or spin a fresh git worktree add … origin/main for the clean baseline. If you inherit a bad pop: git restore --source=HEAD --staged --worktree <foreign tracked files> and rm the foreign untracked files (their data is safe in the still-kept stash), then confirm git stash list is untouched so the owner keeps their entry.

4b. One owner per NEW shared artifact — the add/add conflict that recurs every rebase (2026-07-10, hardcase-capability-run.dispatch-plan.json)

When two PRs each create the same new file path independently, there is no merge base for it — an add/add conflict auto-merge cannot resolve, and it re-surfaces on every rebase until one side wins wholesale. This is exactly what happened to agi-proof/hpo-neural/hardcase-capability-run.dispatch-plan.json: #914 (verifier-integrity sprint) authored a 179-line plan and #925 (capability-track owner) authored a 201-line plan — identical experimentId and schema, two different authors — so #925 conflicted on that path and re-conflicted after every sibling merge moved main under it. The root cause is not the merge; it is two workstreams authoring one artifact. Prevent it:

• A new shared artifact under agi-proof/** (dispatch-plan, evidence doc, run-config) has exactly ONE owning PR — the workstream that actually runs/owns the experiment. Declare it before you create the file: append OWNS: <path> — <session-id> to SESSION-COORDINATION.md (ledger-append-etiquette §1). A path already OWNED by a live session is off-limits to your PR.
• A sibling PR that only references the run links the path — it does NOT commit its own copy. If the verifier sprint wants to say "the hardcase run is staged", it points at the path; it must not author a second version of the plan file. #914 should never have carried a dispatch-plan the capability track owns.
• If two owners genuinely need distinct plans, use distinct paths (suffix run/PR/date) — never two versions at one path.
• Resolving one that already conflicted is the OPPOSITE of the ledger/manifest rule. A plan JSON is a single document, not an append log: take the OWNING side's file whole (git checkout --ours/--theirs -- <path>), then hand-fold any real content from the loser and delete the duplicate. Do not hunk-merge two authors' fields (that yields a Frankenstein plan with both motivation and p0ReviewedBy and a broken schema). Contrast ledger-append-etiquette §4, where you UNION because those files are append logs.

The re-conflict-on-every-rebase tax. #925 also re-conflicted on failure-ledger.md and evidence-manifest.json after #921 and #930 landed: every append-heavy shared file re-diverges each time main moves. When landing N PRs that all touch the ledger/manifest, rebase-chain them (or land back-to-back) and regenerate the manifest as the LAST step (ledger-append-etiquette §3) instead of resolving the same tail N times. evidence-manifest.json is generated — regenerate it (python tools/build_agi_proof_package.py), never hand-merge it.

Stale mergeability cache (distinct from a real behind/dirty). A PR you have proven clean — git merge-base --is-ancestor origin/main HEAD succeeds AND git merge-tree $(git merge-base origin/main HEAD) origin/main HEAD shows zero conflict markers — can still show mergeable: CONFLICTING / mergeStateStatus: DIRTY on GitHub for hours. That is a stale server-side cache (§3a), not a conflict; an empty commit, a real commit, and close/reopen may all fail to clear it. Once fast + ci-complete are green and threads resolved, gh pr merge <N> --squash --admin --delete-branch is the escape hatch (a human's call for a claim-bearing PR — no-overclaim-merge-gate). But re-confirm ancestry first: if --is-ancestor now fails, a sibling has since landed and the conflict is REAL — rebase, do not admin-merge over it.

Branch protection (quick reference)

One ruleset (main-protection) on main: required checks fast + ci-complete; required_review_thread_resolution: true (the silent blocker); required_approving_review_count: 0; required_linear_history: true; direct pushes to main blocked — go through a PR. Repo setting allow_auto_merge: true is on. Verify live before relying on this:

gh api repos/tomyimkc/sophia-agi/rulesets | jq '.[] | {id,name,enforcement}'
gh api repos/tomyimkc/sophia-agi/rules/branches/main \
  | jq '.[] | select(.type=="required_status_checks").parameters.required_status_checks'

Why armed GitHub auto-merge stalls (diagnosed 2026-07-03)

Symptom: PRs go green on every required check yet never auto-merge; the owner merges by hand. Happened on #400, #406, #407, and the whole Gap-2/U-series wave.

The actual root cause is NOT a missing required check. Both required checks, fast and ci-complete, report reliably and pass — verified on the final head of #406 (all 19 check-runs green, including fast and ci-complete). The popular hypothesis ("a required check name that never reports on some PRs") was investigated and falsified for this repo. Two real causes:

1. The arming workflow skips because no PR carries risk:low. .github/workflows/ai-automerge.yml enables GitHub's native auto-merge only if: contains(labels, 'risk:low'). Across the last 12 PRs (#399–#410) none was labeled risk:low, so every enable-automerge run concluded skipped, native auto-merge was never armed, and GitHub had nothing to fire when checks went green. autoMergeRequest was null on #407; on #406 the human armed it manually and it still didn't auto-fire in time.
2. cancel-in-progress: true + a late push turns ci-complete red on the old run. fast-ci.yml and ci.yml cancel in-progress runs on a new push; ci-complete then reports failure (one of its needs was cancelled) on the superseded run. The newest run recovers green, but if auto-merge was armed against the moment the previous run went red, the merge window can be missed.

Recommended fix for the owner (NOT done here — repo settings + labels are the owner's to set):

• Apply risk:low to low-risk PRs so ai-automerge.yml actually arms, or widen its trigger to the labels these PRs already carry (tooling/corpus/benchmark). The label discipline is the lever; the workflow itself is correct.
• Optional belt-and-braces: gate ci-complete's if: always() on github.event.check_suite/head-SHA, or set auto-merge to re-arm on synchronize, so a cancelled sibling run can't shadow the live one.

When a "green but won't merge" happens, check the label and the enable-automerge run conclusion first — not the check list:

gh pr view NNN --json autoMergeRequest,labels   # null autoMergeRequest + no risk:low = never armed
gh run list --workflow=ai-automerge.yml -L1      # conclusion skipped = the arming job did nothing

Stop and ask the human

This skill governs mechanics (stale? blocked? duplicated?). If an action would change what is claimed (a number's status, "validated", a RESULTS.md entry), that is the no-overclaim contract — stop and ask before acting (see the ci-artifact-drift and sophia-agi skills).