@routerhub/agent-rules 1.5.168 → 1.5.169

package/AGENTS.base.md

@@ -117,6 +117,17 @@
 - ⚠️ **已推送到远程的提交需要撤销时，必须用 `git revert`，禁止用 `git push --force` 覆盖远程历史。** `git revert` 会创建一条新的撤销提交，保留完整的操作记录，不影响其他协作者的本地分支；`git push --force` 会破坏远程历史，导致其他人的本地分支与远程脱节，极易引发合并冲突或丢失他人提交。
 - ⚠️ **提交并推送代码后，若发现与主分支存在冲突，必须主动解决**，不能推送完就算完事、把冲突留给别人处理。
 
+## ⚠️ 处理其他项目/副本时统一用 worktree 隔离（不改别人正在用的分支）
+
+- ⚠️ **需要修改某个仓库，而该仓库是多副本（A-/B-/C-/M- 前缀）且当前分支可能正被其他开发任务占用时，默认用临时 git worktree 隔离操作，禁止直接在当前工作副本上 `git checkout` 切换分支。** 多副本仓库中同一个克隆往往同时被多个任务使用：直接切分支会破坏别人正在进行的代码、或把自己卡在非主分支上。实例：`c-pomex-gateway` 正被 `feature/timeslot-pricing` 开发任务占用（落后 main 10 个提交），此时要做文档迁移，就用 `git worktree` 从 `origin/main` 检出到独立目录操作，feature 分支工作区完全不动。
+- ⚠️ **标准操作流程**：
+  1. 在仓库根目录执行 `git worktree add -b <任务分支> ../<任务>-work <基础分支>`（基础分支用 `origin/main` 或具体目标分支），独立目录检出并新建分支，当前工作副本完全不动。
+  2. 在 worktree 目录内完成改动 → 编译/测试通过 → `git push -u origin <任务分支>`。
+  3. 创建 PR（合并目标为仓库默认分支）。
+  4. 操作完成后 `git worktree remove ../<任务>-work` 清理，原副本分支状态不受影响。
+- ⚠️ **worktree 与主副本共享同一套本地 `.git`**，但工作目录、索引、当前分支状态完全独立，不会干扰正在 main 或其他分支上改动代码的协作者。
+- ⚠️ **worktree 目录默认在仓库根目录同级（`../`）**，避免被误当成子文件夹进 git；进入前先确认该路径不存在同名文件夹。
+
 ## ⚠️ PR 冲突修复统一用临时 worktree
 
 - ⚠️ **修复 PR 与主分支的冲突时，一律使用临时 git worktree，禁止直接在当前工作副本上切换分支（`git checkout`）解题。** 原因：A-/B-/C-/M- 多副本仓库中，同一个克隆往往同时被其他开发任务占用；直接切分支会破坏别人正在进行的代码、或把自己卡在非主分支上。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@routerhub/agent-rules",
-  "version": "1.5.168",
+  "version": "1.5.169",
   "description": "Shared Copilot agent rules and guidelines for RouterHub projects",
   "main": "AGENTS.base.md",
   "bin": {

package/rules/global.md

@@ -117,6 +117,17 @@ name: "通用规则"
 - ⚠️ **已推送到远程的提交需要撤销时，必须用 `git revert`，禁止用 `git push --force` 覆盖远程历史。** `git revert` 会创建一条新的撤销提交，保留完整的操作记录，不影响其他协作者的本地分支；`git push --force` 会破坏远程历史，导致其他人的本地分支与远程脱节，极易引发合并冲突或丢失他人提交。
 - ⚠️ **提交并推送代码后，若发现与主分支存在冲突，必须主动解决**，不能推送完就算完事、把冲突留给别人处理。
 
+## ⚠️ 处理其他项目/副本时统一用 worktree 隔离（不改别人正在用的分支）
+
+- ⚠️ **需要修改某个仓库，而该仓库是多副本（A-/B-/C-/M- 前缀）且当前分支可能正被其他开发任务占用时，默认用临时 git worktree 隔离操作，禁止直接在当前工作副本上 `git checkout` 切换分支。** 多副本仓库中同一个克隆往往同时被多个任务使用：直接切分支会破坏别人正在进行的代码、或把自己卡在非主分支上。实例：`c-pomex-gateway` 正被 `feature/timeslot-pricing` 开发任务占用（落后 main 10 个提交），此时要做文档迁移，就用 `git worktree` 从 `origin/main` 检出到独立目录操作，feature 分支工作区完全不动。
+- ⚠️ **标准操作流程**：
+  1. 在仓库根目录执行 `git worktree add -b <任务分支> ../<任务>-work <基础分支>`（基础分支用 `origin/main` 或具体目标分支），独立目录检出并新建分支，当前工作副本完全不动。
+  2. 在 worktree 目录内完成改动 → 编译/测试通过 → `git push -u origin <任务分支>`。
+  3. 创建 PR（合并目标为仓库默认分支）。
+  4. 操作完成后 `git worktree remove ../<任务>-work` 清理，原副本分支状态不受影响。
+- ⚠️ **worktree 与主副本共享同一套本地 `.git`**，但工作目录、索引、当前分支状态完全独立，不会干扰正在 main 或其他分支上改动代码的协作者。
+- ⚠️ **worktree 目录默认在仓库根目录同级（`../`）**，避免被误当成子文件夹进 git；进入前先确认该路径不存在同名文件夹。
+
 ## ⚠️ PR 冲突修复统一用临时 worktree
 
 - ⚠️ **修复 PR 与主分支的冲突时，一律使用临时 git worktree，禁止直接在当前工作副本上切换分支（`git checkout`）解题。** 原因：A-/B-/C-/M- 多副本仓库中，同一个克隆往往同时被其他开发任务占用；直接切分支会破坏别人正在进行的代码、或把自己卡在非主分支上。