adoresever/prepare-pr

Prepare PR

Overview

Prepare a PR head branch for merge with review fixes, green gates, and deterministic merge handoff artifacts.

Inputs

• Ask for PR number or URL.
• If missing, use .local/pr-meta.env from the PR worktree if present.
• If ambiguous, ask.

Safety

• Never push to main or origin/main. Push only to the PR head branch.
• Never run git push without explicit remote and branch. Do not run bare git push.
• Do not run gateway stop commands. Do not kill processes. Do not touch port 18792.
• Do not run git clean -fdx.
• Do not run git add -A or git add ..

Execution Rule

• Execute the workflow. Do not stop after printing the TODO checklist.
• If delegating, require the delegate to run commands and capture outputs.

Completion Criteria

• Rebase PR commits onto origin/main.
• Fix all BLOCKER and IMPORTANT items from .local/review.md.
• Commit prep changes with required subject format.
• Run required gates and pass (pnpm test may be skipped only for high-confidence docs-only changes).
• Push the updated HEAD back to the PR head branch.
• Write .local/prep.md and .local/prep.env.
• Output exactly: PR is ready for /mergepr.

First: Create a TODO Checklist

Create a checklist of all prep steps, print it, then continue and execute the commands.

Setup: Use a Worktree

Use an isolated worktree for all prep work.

repo_root=$(git rev-parse --show-toplevel)
cd "$repo_root"
gh auth status

WORKTREE_DIR=".worktrees/pr-<PR>"
if [ ! -d "$WORKTREE_DIR" ]; then
  git fetch origin main
  git worktree add "$WORKTREE_DIR" -b temp/pr-<PR> origin/main
fi
cd "$WORKTREE_DIR"
mkdir -p .local

Run all commands inside the worktree directory.

Load Review Artifacts (Mandatory)

if [ ! -f .local/review.md ]; then
  echo "Missing .local/review.md. Run /review-pr first and save findings."
  exit 1
fi

if [ ! -f .local/pr-meta.env ]; then
  echo "Missing .local/pr-meta.env. Run /review-pr first and save metadata."
  exit 1
fi

sed -n '1,220p' .local/review.md
source .local/pr-meta.env

Steps

1. Identify PR meta with one API call

pr_meta_json=$(gh pr view <PR> --json number,title,author,headRefName,headRefOid,baseRefName,headRepository,headRepositoryOwner,body)
printf '%s\n' "$pr_meta_json" | jq '{number,title,author:.author.login,head:.headRefName,headSha:.headRefOid,base:.baseRefName,headRepo:.headRepository.nameWithOwner,headRepoOwner:.headRepositoryOwner.login,headRepoName:.headRepository.name,body}'

pr_number=$(printf '%s\n' "$pr_meta_json" | jq -r .number)
contrib=$(printf '%s\n' "$pr_meta_json" | jq -r .author.login)
head=$(printf '%s\n' "$pr_meta_json" | jq -r .headRefName)
pr_head_sha_before=$(printf '%s\n' "$pr_meta_json" | jq -r .headRefOid)
head_owner=$(printf '%s\n' "$pr_meta_json" | jq -r '.headRepositoryOwner.login // empty')
head_repo_name=$(printf '%s\n' "$pr_meta_json" | jq -r '.headRepository.name // empty')
head_repo_url=$(printf '%s\n' "$pr_meta_json" | jq -r '.headRepository.url // empty')

if [ -n "${PR_HEAD:-}" ] && [ "$head" != "$PR_HEAD" ]; then
  echo "ERROR: PR head branch changed from $PR_HEAD to $head. Re-run /review-pr."
  exit 1
fi

2. Fetch PR head and rebase on latest origin/main

git fetch origin pull/<PR>/head:pr-<PR> --force
git checkout -B pr-<PR>-prep pr-<PR>
git fetch origin main
git rebase origin/main

If conflicts happen:

• Resolve each conflicted file.
• Run git add <resolved_file> for each file.
• Run git rebase --continue.

If the rebase gets confusing or you resolve conflicts 3 or more times, stop and report.

3. Fix issues from .local/review.md

• Fix all BLOCKER and IMPORTANT items.
• NITs are optional.
• Keep scope tight.

Keep a running log in .local/prep.md:

• List which review items you fixed.
• List which files you touched.
• Note behavior changes.

4. Optional quick feedback tests before full gates

Targeted tests are optional quick feedback, not a substitute for full gates.

If running targeted tests in a fresh worktree:

if [ ! -x node_modules/.bin/vitest ]; then
  pnpm install --frozen-lockfile
fi

5. Commit prep fixes with required subject format

Use scripts/committer with explicit file paths.

Required subject format:

• fix: <summary> (openclaw#<PR>) thanks @<author>

commit_msg="fix: <summary> (openclaw#$pr_number) thanks @$contrib"
scripts/committer "$commit_msg" <changed file 1> <changed file 2> ...

If there are no local changes, do not create a no-op commit.

Post-commit validation (mandatory):

subject=$(git log -1 --pretty=%s)
echo "$subject" | rg -q "openclaw#$pr_number" || { echo "ERROR: commit subject missing openclaw#$pr_number"; exit 1; }
echo "$subject" | rg -q "thanks @$contrib" || { echo "ERROR: commit subject missing thanks @$contrib"; exit 1; }

6. Decide verification mode and run required gates before pushing

If you are highly confident the change is docs-only, you may skip pnpm test.

High-confidence docs-only criteria (all must be true):

• Every changed file is documentation-only (docs/**, README*.md, CHANGELOG.md, *.md, *.mdx, mintlify.json, docs.json).
• No code, runtime, test, dependency, or build config files changed (src/**, extensions/**, apps/**, package.json, lockfiles, TS/JS config, test files, scripts).
• .local/review.md does not call for non-doc behavior fixes.

Suggested check:

changed_files=$(git diff --name-only origin/main...HEAD)
non_docs=$(printf "%s\n" "$changed_files" | grep -Ev '^(docs/|README.*\.md$|CHANGELOG\.md$|.*\.md$|.*\.mdx$|mintlify\.json$|docs\.json$)' || true)

docs_only=false
if [ -n "$changed_files" ] && [ -z "$non_docs" ]; then
  docs_only=true
fi

echo "docs_only=$docs_only"

Bootstrap dependencies in a fresh worktree before gates:

if [ ! -d node_modules ]; then
  pnpm install --frozen-lockfile
fi

Run required gates:

pnpm build
pnpm check

if [ "$docs_only" = "true" ]; then
  echo "Docs-only change detected with high confidence; skipping pnpm test." | tee -a .local/prep.md
else
  pnpm test
fi

Require all required gates to pass. If something fails, fix, commit, and rerun. Allow at most 3 fix-and-rerun cycles.

7. Push safely to the PR head branch

Build prhead from owner/name first, then validate remote branch SHA before push.

if [ -n "$head_owner" ] && [ -n "$head_repo_name" ]; then
  head_repo_push_url="https://github.com/$head_owner/$head_repo_name.git"
elif [ -n "$head_repo_url" ] && [ "$head_repo_url" != "null" ]; then
  case "$head_repo_url" in
    *.git) head_repo_push_url="$head_repo_url" ;;
    *) head_repo_push_url="$head_repo_url.git" ;;
  esac
else
  echo "ERROR: unable to determine PR head repo push URL"
  exit 1
fi

git remote add prhead "$head_repo_push_url" 2>/dev/null || git remote set-url prhead "$head_repo_push_url"

echo "Pushing to branch: $head"
if [ "$head" = "main" ] || [ "$head" = "master" ]; then
  echo "ERROR: head branch is main/master. This is wrong. Stopping."
  exit 1
fi

remote_sha=$(git ls-remote prhead "refs/heads/$head" | awk '{print $1}')
if [ -z "$remote_sha" ]; then
  echo "ERROR: remote branch refs/heads/$head not found on prhead"
  exit 1
fi
if [ "$remote_sha" != "$pr_head_sha_before" ]; then
  echo "ERROR: expected remote SHA $pr_head_sha_before, got $remote_sha. Re-fetch metadata and rebase first."
  exit 1
fi

git push --force-with-lease=refs/heads/$head:$pr_head_sha_before prhead HEAD:$head || push_failed=1

If lease push fails because head moved, perform one automatic retry:

if [ "${push_failed:-0}" = "1" ]; then
  echo "Lease push failed, retrying once with fresh PR head..."

  pr_head_sha_before=$(gh pr view <PR> --json headRefOid --jq .headRefOid)
  git fetch origin pull/<PR>/head:pr-<PR>-latest --force
  git rebase pr-<PR>-latest

  pnpm build
  pnpm check
  if [ "$docs_only" != "true" ]; then
    pnpm test
  fi

  git push --force-with-lease=refs/heads/$head:$pr_head_sha_before prhead HEAD:$head
fi

8. Verify PR head and base relation (Mandatory)

prep_head_sha=$(git rev-parse HEAD)
pr_head_sha_after=$(gh pr view <PR> --json headRefOid --jq .headRefOid)

if [ "$prep_head_sha" != "$pr_head_sha_after" ]; then
  echo "ERROR: pushed head SHA does not match PR head SHA."
  exit 1
fi

git fetch origin main
git fetch origin pull/<PR>/head:pr-<PR>-verify --force
git merge-base --is-ancestor origin/main pr-<PR>-verify && echo "PR is up to date with main" || (echo "ERROR: PR is still behind main, rebase again" && exit 1)
git branch -D pr-<PR>-verify 2>/dev/null || true

9. Write prep summary artifacts (Mandatory)

Write .local/prep.md and .local/prep.env for merge handoff.

contrib_id=$(gh api users/$contrib --jq .id)
coauthor_email="${contrib_id}+${contrib}@users.noreply.github.com"

cat > .local/prep.env <<EOF_ENV
PR_NUMBER=$pr_number
PR_AUTHOR=$contrib
PR_HEAD=$head
PR_HEAD_SHA_BEFORE=$pr_head_sha_before
PREP_HEAD_SHA=$prep_head_sha
COAUTHOR_EMAIL=$coauthor_email
EOF_ENV

ls -la .local/prep.md .local/prep.env
wc -l .local/prep.md .local/prep.env

10. Output

Include a diff stat summary:

git diff --stat origin/main..HEAD
git diff --shortstat origin/main..HEAD

Report totals: X files changed, Y insertions(+), Z deletions(-).

If gates passed and push succeeded, print exactly:

PR is ready for /mergepr

Otherwise, list remaining failures and stop.

Guardrails

• Worktree only.
• Do not delete the worktree on success. /mergepr may reuse it.
• Do not run gh pr merge.
• Never push to main. Only push to the PR head branch.
• Run and pass all required gates before pushing. pnpm test may be skipped only for high-confidence docs-only changes, and the skip must be explicitly recorded in .local/prep.md.