gss-restack-with-git-machete

name	gss_restack_with_git_machete
description	Drive git-machete to restack/rebase a gss feature worker stack when `gss feature conflicts` reports overlap or a checkpoint/rebase/restack aborts on conflict. Local rebase helper only — gss remains the single writer for PRs and the registry.

Restack a gss stack with git-machete

gss itself ships no stack-rebase engine (design.md → "Companion rebase tooling", resolution #14). Its built-in baseline is git config rebase.updateRefs true (set in every worktree it creates), which restacks descendants during an ordinary interactive rebase. When that isn't enough — a multi-branch stack needs reordering, or a gss feature command aborts on a rebase conflict — this skill drives git-machete as a local restack helper.

License (verified before recommending)

• Tool: git-machete — https://github.com/VirtusLab/git-machete
• License: MIT — Allowed/permissive per src/CLAUDE.md → Library standards. Not GPL/AGPL/LGPL, not cloud-gated/SaaS.
• LICENSE blob (pinned): https://github.com/VirtusLab/git-machete/blob/master/LICENSE git blob SHA 2605254a8861c08d7a77813101e41de912959f2f ("MIT License — Copyright (c) 2017-2024 VirtusLab", verified verbatim from the canonical upstream raw LICENSE).
• Version: require git-machete >= 3.20 (the verb set below is stable across 3.x); validated against v3.41.0 (May 2026). If git machete --version reports < 3.20 or >= 4.0, stop and ask the user to install a supported version rather than guessing at changed flags.

Verb allowlist (Security boundary — do not exceed)

git-machete is used only as a local branch-tree / rebase tool. gss is the single writer for GitHub PRs and registry.json; this skill must never let git-machete mutate either.

Allowed:

Verb	Why	Mutates?
git machete --version	preflight version gate	no
git machete status	show the branch tree + sync state	no (read-only)
git machete fork-point <branch>	inspect where a branch diverged	no (read-only)
git machete update --no-interactive-rebase	rebase the current branch onto its parent, non-interactively	yes (local history)
git machete traverse --fetch --start-from=here	walk the stack, rebasing each branch onto its parent with conflict prompts	yes (local history)

Disallowed (never run these from this skill):

• git machete github ... (create-pr, retarget-pr, checkout-prs, anno-prs, …) — PRs are gss's job. Letting git-machete open/retarget PRs would desync registry.json from GitHub. After any restack, re-run the matching gss feature command so gss updates PR bases + the registry.
• git machete delete-unmanaged, git machete slide-out — these remove or collapse branches; deletion/teardown is gss feature done's job.
• Any --push / force-push flags — gss owns pushes (--force-with-lease inside its orchestrators).

If a situation seems to require a disallowed verb, stop and hand back to the user with the diagnosis; do not improvise.

When to use

• gss feature conflicts reports files touched by more than one worker and the user wants to linearize/rebase the stack before resolving.
• gss feature checkpoint / rebase / restack aborts with ErrRebaseConflict and the stack needs a guided, multi-branch restack.

Prerequisites

• git-machete installed (MIT). Linux: pipx install git-machete (or sudo apt-get install git-machete where packaged). macOS: brew install git-machete. Confirm with git machete --version.
• A gss feature stack already exists (run gss feature list --tree to see it).
• You are operating inside the repo (not a stripped checkout).

Steps

1. Preflight

Run git machete --version and confirm it is >= 3.20 and < 4.0. If not, stop and ask the user to install a supported version.

2. Discover the stack

Run gss feature list --tree to see gss's view, then git machete status. If git-machete has no definition file yet (.git/machete), build one from the gss stack: the worker branches and their base_branch links map directly onto machete's parent/child tree. Prefer git machete discover --list-commits and let the user confirm the inferred tree before editing.

3. Restack

• Single branch onto its (already-correct) parent: git machete update --no-interactive-rebase.
• Whole stack: git machete traverse --fetch --start-from=here and resolve conflicts in the worktree as prompted (git-machete pauses; the user fixes + git rebase --continue).

4. Hand back to gss

git-machete only rewrote local history. Now let gss reconcile PRs + registry:

• Re-run gss feature checkpoint (or gss feature rebase) in each affected worker so gss force-pushes with lease and updates the PR base/body.
• If a parent merged, gss feature merged <ref> already handles re-targeting — use git-machete only for the local rebase, not the PR retarget.

5. Report

Summarize what was restacked, which branches moved, and which gss feature commands the user should run (or that you ran) to bring PRs back in sync. Never claim a PR was updated unless a gss command did it.