chore(workflow): add upstream preflight sync script

scripts/openclaw-upstream-preflight.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Ensure upstream clone is synced before implementing OpenClaw code changes.
+# Usage:
+#   scripts/openclaw-upstream-preflight.sh
+#   scripts/openclaw-upstream-preflight.sh fix/my-change
+
+REPO="${OPENCLAW_UPSTREAM_REPO:-$HOME/.openclaw/workspace/external/openclaw-upstream}"
+TARGET_BRANCH="${1:-}"
+
+if [[ ! -d "$REPO/.git" ]]; then
+  echo "error: upstream repo not found at $REPO" >&2
+  echo "hint: git clone https://github.com/openclaw/openclaw $REPO" >&2
+  exit 2
+fi
+
+cd "$REPO"
+
+echo "[preflight] syncing upstream..."
+git fetch --all --prune
+git checkout main
+git pull --rebase
+
+if [[ -n "$(git status --porcelain)" ]]; then
+  echo "error: working tree is not clean on main; resolve before branching" >&2
+  git status --short
+  exit 3
+fi
+
+if [[ -n "$TARGET_BRANCH" ]]; then
+  if git show-ref --verify --quiet "refs/heads/$TARGET_BRANCH"; then
+    echo "[preflight] switching to existing branch: $TARGET_BRANCH"
+    git checkout "$TARGET_BRANCH"
+    echo "[preflight] rebasing $TARGET_BRANCH onto origin/main"
+    git rebase origin/main
+  else
+    echo "[preflight] creating branch: $TARGET_BRANCH"
+    git checkout -b "$TARGET_BRANCH"
+  fi
+fi
+
+MAIN_HEAD_LOCAL=$(git rev-parse --short main)
+MAIN_HEAD_REMOTE=$(git rev-parse --short origin/main)
+AB=$(git rev-list --left-right --count main...origin/main)
+CUR=$(git rev-parse --abbrev-ref HEAD)
+
+echo "[preflight] branch: $CUR"
+echo "[preflight] main local:  $MAIN_HEAD_LOCAL"
+echo "[preflight] main remote: $MAIN_HEAD_REMOTE"
+echo "[preflight] main ahead/behind (local remote): $AB"
+echo "[preflight] done"

scripts/openclaw-upstream-workflow.md

@@ -9,6 +9,14 @@ Use this whenever modifying OpenClaw itself.
 
 ## Standard flow
 
+Quick preflight helper (recommended):
+
+```bash
+scripts/openclaw-upstream-preflight.sh fix/<short-topic>
+```
+
+Equivalent manual flow:
+
 ```bash
 cd external/openclaw-upstream
 git fetch --all --prune