From b36ab896243a8c73570fa8a55d8c4ec4511c0e22 Mon Sep 17 00:00:00 2001
From: zap <zap@local>
Date: Wed, 4 Mar 2026 23:15:37 +0000
Subject: [PATCH] docs(workflow): require rebase-first + rebase-and-merge
 policy

---
 AGENTS.md                             | 10 +++++++---
 scripts/openclaw-upstream-workflow.md | 13 ++++++++++---
 2 files changed, 17 insertions(+), 6 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 0be1cc5..ca99410 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -130,7 +130,7 @@ Skills provide your tools. When you need one, check its `SKILL.md`. Keep local n
 - Commit frequently in small, meaningful checkpoints.
 - Use Conventional Commits format: `type(scope): summary`.
 - Create a feature branch when work is non-trivial, multi-step, or risky.
-- Keep `main` stable; merge focused changes back after verification.
+- Keep `main` stable; use **rebase-first history** and prefer **Rebase and merge** for PRs after verification.
 - Before commit, quickly check staged diff and avoid committing secrets/runtime noise.
 
 ### OpenClaw upstream workflow (required for core code changes)
@@ -139,11 +139,15 @@ Skills provide your tools. When you need one, check its `SKILL.md`. Keep local n
 - Do **not** rely on editing installed dist files under `~/.npm-global/.../dist` as the long-term fix path.
 - For OpenClaw code changes:
   1. `cd external/openclaw-upstream`
-  2. `git fetch --all --prune && git checkout main && git pull --ff-only`
+  2. `git fetch --all --prune && git checkout main && git pull --rebase`
   3. Create a focused branch (`fix/...`, `feat/...`, `chore/...`)
   4. Implement in `src/` and add/adjust tests
   5. Run relevant tests before commit
-  6. Commit, push branch, and open PR
+  6. Rebase branch onto latest `main` before push/PR (`git fetch origin && git rebase origin/main`)
+  7. Commit, push branch, and open PR
+- PR merge strategy for OpenClaw upstream:
+  - prefer **Rebase and merge**
+  - avoid merge commits unless explicitly needed for special cases
 - If an emergency local dist hotfix is unavoidable, also:
   - capture an idempotent patch script in `scripts/`
   - document rollback/update behavior
diff --git a/scripts/openclaw-upstream-workflow.md b/scripts/openclaw-upstream-workflow.md
index f974898..402567d 100644
--- a/scripts/openclaw-upstream-workflow.md
+++ b/scripts/openclaw-upstream-workflow.md
@@ -13,7 +13,7 @@ Use this whenever modifying OpenClaw itself.
 cd external/openclaw-upstream
 git fetch --all --prune
 git checkout main
-git pull --ff-only
+git pull --rebase
 git checkout -b fix/<short-topic>
 ```
 
@@ -21,7 +21,14 @@ Then:
 1. Implement in `src/` (and docs/tests as needed).
 2. Run targeted tests first; run broader suite if change touches shared paths.
 3. Commit with Conventional Commit format.
-4. Push branch and open PR.
+4. Rebase onto latest `main` before push/PR:
+   - `git fetch origin && git rebase origin/main`
+5. Push branch and open PR.
+
+## Merge policy
+
+- Preferred PR strategy: **Rebase and merge**
+- Avoid merge commits unless explicitly required for a special case
 
 ## Branch naming
 
@@ -42,7 +49,7 @@ scripts/openclaw-update-safe.sh
 - After runtime update, re-sync upstream clone before new changes:
 
 ```bash
-cd external/openclaw-upstream && git fetch --all --prune && git checkout main && git pull --ff-only
+cd external/openclaw-upstream && git fetch --all --prune && git checkout main && git pull --rebase
 ```
 
 ## Emergency dist hotfix policy