mcp-ai-wpoos-git-ops
Git/GitHub workflow discipline for the mcp-ai-wpoos repo — PRs against `alpha-working` with owner-merge, commit style, staged commits (no `git add -A`), the stacked-PR rebase recipe for when a parent
SKILL.md.agents/skills/mcp-ai-wpoos-git-ops/SKILL.md
GitHubmcp-ai-wpoos — Git & PR ops
Branch & PR discipline
- PR base is
alpha-working. The owner merges manually — agents never merge their own PRs. Clusters land as one PR per cluster (see themcp-ai-wpoos-test-suiteskill for the cluster workflow). - Branch naming:
feat/<track>-<descriptor>; stack dependent work on top of the unmerged parent branch and say so in the PR body. - Stage explicitly. Never
git add -A— the worktree often holds build artifacts and local state (e.g..lighthouseci/,test-results/). Use explicit paths, or pathspec exclusions:git add examples/nvoos-astro-velocity ":(exclude)…/test-results". - Commits: imperative subject ≤ 50 chars, body only when useful (wrap at 72).
Run commits with
GIT_EDITOR=true git commit …; read-only git with--no-pager; prefergit --no-optional-locks status.
Stacked PRs after a squash merge (the recipe that works)
When the parent PR was squash-merged, a stacked branch shows add/add conflicts on every file both sides "added" — even when the squashed tree is byte-identical to your baseline. Fix by rebasing only your delta onto the updated base:
git fetch origin alpha-working
# Optional diagnosis — exits 1 when conflicts exist:
git merge-tree --write-tree origin/alpha-working HEAD
# Verify the squash tree equals your old baseline (empty diff = clean replay ahead):
git diff <squash-merge-sha> <old-baseline-sha>
# Replay only the commits after the baseline:
git rebase --onto origin/alpha-working <old-baseline-sha> <branch>
git push --force-with-lease origin <branch>
- Expect zero conflicts during the replay when the squash tree matches your baseline; conflicts mean something else changed — abort and investigate before continuing.
- After the rebase the PR shows only your delta; re-verify
gh pr view <n> --json mergeable,mergeStateStatus(MERGEABLE). - GitHub Docs reference: "Managing stacked pull requests" /
"Troubleshooting stacked pull requests" (
gh stack rebasealternative).
Shared worktree discipline (multi-agent repo, learned 2026-10-30)
Parallel agents share the same checkout and switch branches between tasks. Four rules, each from a session that cost a recovery:
- Check the branch before committing.
git branch --show-currentandgit log --oneline -1beforegit add/commit— a commit lands on whatever branch is checked out, and the worktree may have been switched under you (a build fix once landed on another agent'sfeat/mcp-sdk-skill-updates). - Recovering a stray commit: cherry-pick it onto your branch, then
restore the foreign branch with
git reset --mixed <its-old-head>+git restore --worktree -- <only-the-files-you-touched>. Nevergit reset --hardin a shared worktree — it wipes other agents' uncommitted tracked edits (e.g. a modifiedSKILL.md). - Rebasing with foreign unstaged edits present: plain
git rebaserefuses ("You have unstaged changes"); usegit rebase --autostash— it stashes only tracked changes and pops them back. - Merged PRs freeze their head. A squash-merged (closed) PR stops
tracking branch pushes —
gh pr viewkeeps showing the stalehead_sha. After the owner merges, run the stacked-PR recipe above and open a fresh PR for the delta (PRs #7302 → #7303). - Multiple linked worktrees exist — aim every git command. Other
agents keep
git worktree addcheckouts (seegit worktree list). Agit cherry-pickrun from the wrong directory acts on the wrong worktree (2026-10-31: one silently no-op'd in the main worktree while the target was a linked one — caught by the "cherry-pick is now empty" message). Checkgit rev-parse --show-toplevelfirst, or usegit -C <abs-worktree-path>for any command aimed at another worktree. - Dirty shared worktree + moved base →
git worktree add, never a checkout. Whenorigin/alpha-workingadvanced and other agents' uncommitted files blockgit checkout -b("would be overwritten by checkout"), don't stash their work:git worktree add ../<name> -b <branch> origin/alpha-working, then operate there viagit -C(andnpm pack <abs-dir>rather than--prefix).git worktree removewhen done — the shared checkout was never touched. - De-stack a PR without
reset --hard: move the branch back withgit reset --mixed <parent>(worktree untouched), restore only your own paths withgit restore --worktree -- <your-paths>(a file you created becomes untracked again — plainrm), thengit push --force-with-lease. Other agents' unstaged edits survive byte-for-byte. Verified 2026-10-31 de-stacking PR #7325. - Sibling PRs editing the same file (the #7348 ↔ #7349 case, 2026-11-01):
two open PRs touch the same docs file in overlapping hunks; the later one
merges first and the earlier one reports merge conflicts at merge time.
Fix:
git fetch origin→git checkout <branch>→GIT_EDITOR=true git rebase --autostash origin/alpha-working, resolve by keeping both PRs' intents (the merged PR's new text usually wins for shared lines; your PR's unique additions stay), thengit push --force-with-lease. A successful rebase replay is proof the conflict is gone — by construction the branch is ahead of the base. - Local
.git/info/excludecan silently block deliberate files. The main worktree ignores*.png/*.jpg(per-worktree media guard, not repo config).git addthen fails with "ignored by one of your .gitignore files" — rungit check-ignore -v <path>to find the rule andgit add -fwhen the file is deliberate (gateway logo assets, PR #7349).
Windows reserved-name artifacts (learned 2026-10-29)
A stray untracked file literally named nul (Windows reserved device name)
can appear in the repo root. Two failure modes follow:
git stash push -uaborts partway withfailed to remove nul: Permission denied— the stash IS saved, but tracked files stay modified and the untracked files get hidden in the stash's third parent. Recovery: list withgit ls-tree -r --name-only "stash@{N}^3"and restore withgit checkout "stash@{N}^3" -- <paths>(excludetest-results/). When only a few tracked files block a branch switch onto a moved base, the lighter tool is a pathspec stash:git stash push -m <msg> -- <paths>, switch, thengit checkout stash@{0} -- <paths>.- Deleting the file itself: normal
rm/delfail (device semantics). Write a tiny.ps1usingRemove-Item -LiteralPath "\\?\<abs-path>"(forward slashes OK after the prefix) and run it withpowershell -NoProfile -ExecutionPolicy Bypass -File— inline-Commandcalls get the backslashes mangled by the sh layer. Never stage it — explicit staging (above) keeps it out of commits.
Windows sh-shell gotchas (learned 2026-11-01, gateway session)
- The terminal runs sh, not cmd:
copydoes not exist — usecp;del/renarerm/mv. powershell -Commandinline strings get$varinterpolated away by the sh layer (every$ivanished → parser errors). Write a.ps1file and runpowershell -NoProfile -ExecutionPolicy Bypass -File, or do it in node instead (e.g. JPEG/PNG dimension sniffing from the file header — no deps needed).findstr /C:"..."quoting breaks under sh — pipe to node for filtering or use the terminal tool'stail_lines.node --test <directory>does not recurse on this setup (runs one file) — pass explicit files or the package'snpm testscript.- Windows-reserved names: see the
nul-artifact section above (samepowershell -Filepattern applies).
gh CLI gotchas
git archivestripspackage.jsonandbin/repo-wide — the root.gitattributesexport-ignores them (meant for the plugin's release zips). Nevergit archive <rev> packages/<pkg>to extract package content (silently incomplete tar) — copy from a worktree checkout instead.gh workflow run <name>404s unless the workflow file exists on the default branch (main) — foralpha-working-only workflows dispatch via the API (POST /actions/workflows/<id>/dispatcheswithref=alpha-working) or push a trigger.gh pr checks <n>shows queued runs; the repo-wide PHP Linting workflow takes ~20–30 minutes — don't retry or "fix" it while it's simply running.- After a forced push, GitHub recomputes conflict status automatically;
re-check
mergeablebefore reporting done.
PR hygiene
- PR body states: what changed, validation actually run (with counts), and — for stacked PRs — the parent PR number and that the diff delta is the last commit.
- Don't claim validation that wasn't run. Reference files by project-relative path.