docs: require task worktrees for G14 development

2026-05-26 21:37:17 +08:00
parent 58468159c3
commit cedcb7f4c0
3 changed files with 5 additions and 1 deletions
@@ -27,6 +27,7 @@ HWLAB 是硬件实验室运行面和控制面项目。本文是 agent、指挥
 ## 工作区

 - G14 分支固定 source workspace 是 G14 节点上的 `/root/hwlab`，固定使用 `G14` 分支和 `origin git@github.com:pikasTech/HWLAB.git`。在 G14 上进行代码、文档、GitOps render、Tekton/poller/Argo CD 修复或 CI/CD 验证前，必须先确认 `pwd` 为 `/root/hwlab` 且 `git status --short --branch` 为 `G14...origin/G14`；不满足时先停止并修正 workspace。
+- G14 开发默认先以 `/root/hwlab` 做固定 repo 预检，再在 `/root/hwlab/.worktree/<task>` 从最新 `origin/G14` 创建独立 worktree 修改和提交；固定 repo 不作为并行任务 scratch 区，详见 [docs/reference/commander-collaboration.md](docs/reference/commander-collaboration.md)。
 - G14 k3s 操作必须通过 UniDesk SSH route `G14:k3s` 执行，例如 `bun scripts/cli.ts ssh G14:k3s kubectl get pods -n hwlab-ci`；禁止使用 `ssh G14 k3s ...`。不要把 `/workspace/hwlab`、`/root/HWLAB`、D601 workspace、master-server checkout 或临时 clone 当作 G14 分支 source truth。
 - Runner 和指挥常用工作区是 `/workspace/hwlab`；进入仓库先检查分支与工作树状态，详见 [docs/reference/commander-collaboration.md](docs/reference/commander-collaboration.md)。
 - G14 CI/CD 由 `G14` source branch、G14 k3s Tekton 和 `G14-gitops` branch 驱动；需要构建、Playwright、check、发布预检或运行面验证时放到 G14 k3s/runner/CI/CD，不在 master server 跑重型验证。
@@ -16,6 +16,8 @@

 - 常规 runner 和指挥官工作区是 `/workspace/hwlab`。
 - 进入仓库先检查分支和工作树状态。
+- G14 人工/指挥官开发必须先在固定 repo `/root/hwlab` 做 `pwd`、`git status --short --branch`、`git remote -v` 和 `fetch` 预检，再在 `/root/hwlab/.worktree/<task>` 从最新 `origin/G14` 创建任务专属 worktree；代码、文档、测试补丁、提交和 PR 准备都在该独立 worktree 中完成。
+- 固定 repo `/root/hwlab` 是 source truth 和 worktree 管理入口，不是并行任务 scratch 区；不要在固定 repo 根目录堆叠未提交改动，也不要复用其他任务遗留 `.worktree/<task>`。
 - D601 发布和 rollout 工作区是 `/home/ubuntu/workspace/hwlab`。
 - 不要清理、reset 或复用无关 runner worktree 作为发布真相。

@@ -192,7 +192,8 @@ G14 PR、CI、CD 的判断应按以下顺序收敛真相，越靠前越接近最
 bun scripts/cli.ts ssh G14:/root/hwlab shell 'git status --short --branch && git remote -v | sed -n "1,4p"'
 ```

- 只有 `/root/hwlab` 已经是 `G14...origin/G14` 时才继续；否则先从 `origin/G14` 建干净临时 worktree，再开始本轮修改。
+- `/root/hwlab` 是固定 source workspace 和 worktree 管理入口；完成预检后，在 `/root/hwlab/.worktree/<task>` 从最新 `origin/G14` 创建任务专属 worktree，再开始本轮代码、文档、测试和提交修改。
+- 只有独立 worktree 跟踪正确 base 且 `git status` 只包含本任务文件时才继续；不要在 `/root/hwlab` 根目录直接堆叠并行开发改动，也不要复用其他任务遗留 worktree。
 - k3s 只走 `G14:k3s`；不要混用 D601 kubeconfig、master server 执行面或旧 SSH route 语法。

 2. Source / PR 预检