Update Branch

A rebase rewrites published history, so every step that can lose work has a check in front of it. The branch defaults to the current branch, and the base defaults to origin/HEAD. The word merge asks for a merge.

Step 1: Pick the workspace

PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(dirname "$(dirname "$(readlink -f "<skill_dir>/SKILL.md")")")}"
python3 "$PLUGIN_ROOT/scripts/prepare_update_workspace.py" [--branch <branch>] [--base <base>]

The helper fetches, then prints MODE:, BASE:, and WORKSPACE_PATH:. Run every later command in that path, with git -C <workspace_path> for git. On STOP: <reason>, show the reason and stop. Never stash, reset, or discard work to get past a refusal.

Step 2: Protect the remote commits

Record origin/<branch> as the lease for Step 6. A branch with no remote ref was never pushed, so skip the rest of this step.

A rebase and a forced push delete the commits in <branch>..origin/<branch> from the remote. If the local branch has nothing of its own past origin/<branch>, fast-forward to it. Otherwise the two diverged, so show both sides and ask.

Step 3: Choose rebase or merge

Rebase by default. When one of these is true, propose a merge and wait for the answer:

• <BASE>..origin/<branch> holds commits by another author than git config user.email.
• The repository docs ask for merge commits.
• The user asked for a merge.

Never switch strategy without consent.

Step 4: Update the branch

Read the conflict conventions in the repository docs before you resolve a conflict. Keep the intent of both sides, and read the base commit that touched the same lines. Record each resolution for the report, including any edit outside the conflict markers.

If the right answer to a conflict is not clear from the code, stop and ask. If the same lines conflict in commit after commit, abort the rebase and offer a merge.

Step 5: Build and test

Build the projects in git diff --name-only <BASE>...HEAD, and run their unit and integration tests. When a shared library changed, also test its dependents. Take the commands from the repository docs and build files. If you find none, ask.

Step 6: Push and report

The call to /update-branch gives permission to push when the risk is low. The risk is low when all of these are true:

• The build and every test from Step 5 passed, and Step 5 tested each changed project.
• Step 4 resolved no conflict.
• After a rebase, git config user.email is the author of every commit in <BASE>..origin/<branch>.

If one condition is false, do not push. Report the false conditions and the exact push command, then ask. If a build or a test failed, stop there.

After a rebase, push with the lease from Step 2:

git -C <workspace_path> push --force-with-lease=<branch>:<lease> origin <branch>

If the lease fails, stop and report it. Do not retry with a new lease. After a merge, use a plain git push, with -u for a branch that was never pushed. Never use --force, -f, or a +<refspec>.

Then report the strategy, the new base commit, each conflict resolution, the build and test results, and the push result.

Step 7: Clean up

Only MODE: worktree belongs to this run. After a successful push, remove it with the helper, never with git worktree remove:

python3 "$PLUGIN_ROOT/scripts/prepare_update_workspace.py" --remove <workspace_path>

Git removes a clean worktree with unpushed commits. The helper refuses it. If the helper prints STOP: or the branch was not pushed, keep the worktree and give the user its path.