From dbd28a0f758854b91029f203953dcb5a4fee9b54 Mon Sep 17 00:00:00 2001 From: Codex Date: Wed, 1 Jul 2026 06:48:22 +0000 Subject: [PATCH] docs: clarify fixed worktree sync rules --- AGENTS.md | 4 ++-- docs/reference/devops-hygiene.md | 8 +++++--- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index a1820a12..993d7d35 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,7 +4,7 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台。本文 ## P0: 主 worktree 同步提交第一原则 -- P0: 主 worktree 同时存在脏改且落后 `origin/master` 时，必须先 `git stash push -u` 保存当前脏改（包含 untracked），再 `git pull --ff-only origin master` 快进到最新 `master`，然后 `git stash apply` 并按语义合并，确认 diff 后 `git commit` 并 `git push origin master`；禁止用 reset、drop 或覆盖式 checkout 丢弃并行改动。 +- P0: 发现固定主/目标 worktree 落后 remote 时，必须立刻先 `git stash push -u` 保存脏改（如有，含 untracked），再 `git pull --ff-only` 快进到最新 remote，然后 `git stash apply` 并按语义合并后继续；禁止用 reset、drop 或覆盖式 checkout 丢弃并行改动。 ## P0: backend-core 运行面冻结 @@ -21,7 +21,7 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台。本文 - P0: 本机可能有多个并行开发任务；发现未预期本地修改时默认保留，不得自动 `git reset`、`git checkout --`、删除或回滚他人修改。 - P0: 当前目录的主工作区（非 `.worktree/` 路径）必须固定停留在 `master` 分支；禁止把主工作区切到其他分支，非 `master` 开发必须使用独立 `.worktree/`。 - P0: 主 worktree 同步冲突处理以文件开头的“主 worktree 同步提交第一原则”为最高入口；语义合并时保留并行改动的有效意图，不回滚到旧运行面或旧配置路径。 -- P0: 固定主 repo 通常只做 source-truth 预检、fetch、status 和 worktree anchor；源码、配置、部署脚本、issue closeout 和高风险 dad-dev 工作必须使用独立 `.worktree/`。文档/skill/长期参考轻量修改可直接在当前主 worktree 处理。细则见 `docs/reference/devops-hygiene.md`。 +- P0: 固定主 repo 通常只做 source-truth 预检、fetch、status、快进同步和 worktree anchor；源码、配置、部署脚本、issue closeout 和高风险 dad-dev 工作必须使用独立 `.worktree/`，PR 合并后及时快进固定主 worktree。文档/skill/长期参考轻量修改可直接在当前主 worktree 处理。细则见 `docs/reference/devops-hygiene.md`。 - P0: 清理任务 worktree 前必须按语义确认已合入 `master`：工作区 clean，相关提交是 `origin/master` 祖先或被 `--cherry-pick` 判定为等价吸收，必要时检查关键文件 diff/PR merge commit；不得仅因分支落后就删除。仍有未合入语义、未提交文件或不确定归属时，先合并/提交/推送到 `master` 或记录阻塞，不清理 worktree。 - P0: UniDesk 工具链自身修复必须先合并到 `master`，再把实际执行工具命令的 checkout 更新到包含该 merge 的最新 `master` 后继续使用；若当前 checkout 有并行脏改或非 master 分支导致不能安全 fast-forward，禁止 reset/stash/checkout 清理，改用干净 `origin/master` worktree 运行工具并说明原因。 - P0: Master server 禁止作为通用构建机；不得在 master server 执行 Docker/Rust/Go/前端等高 CPU 构建。受控例外见 `docs/reference/dev-environment.md`。 diff --git a/docs/reference/devops-hygiene.md b/docs/reference/devops-hygiene.md index f3f09b1b..635ae740 100644 --- a/docs/reference/devops-hygiene.md +++ b/docs/reference/devops-hygiene.md @@ -48,13 +48,15 @@ If a manual repair is needed to unblock the platform, the durable fix must be co “分布式敏捷”是 UniDesk 对 distributed agile field repair 的固定流程名；通用 P1/P2/P3/P4 阶段、禁止行为和证据边界由 `$dad-dev` skill 维护，本参考不再重复展开。UniDesk 项目内只保留下面的特有约束：必须使用结构化 `trans`/UniDesk CLI 进入真实 provider、pod、host bridge 或 service port；运行面热补只能证明方向或临时恢复，不能成为隐藏部署真相；持久化完成必须回到 Git/PR/CI/CD 后原入口复测。 -固定主 repo 是 source truth anchor，不是源码/运行面 scratch 区。会产生源码、配置、issue closeout、部署脚本、验收产物或高风险 dad-dev / post-task 交付的工作，执行前必须先从目标 fixed repo 的最新 remote/base 创建任务专属 `.worktree/`，后续编辑、验证、提交、push 和受控 CLI 写操作都在该 worktree 内完成。fixed repo 只用于 `git fetch`、`git status`、读取规则和 `git worktree add`；其中已有的并行未提交修改默认保持不动，不纳入当前任务，也不要用 reset、checkout 或删除来“清理”。 +固定主 repo 是 source truth anchor，不是源码/运行面 scratch 区。会产生源码、配置、issue closeout、部署脚本、验收产物或高风险 dad-dev / post-task 交付的工作，执行前必须先从目标 fixed repo 的最新 remote/base 创建任务专属 `.worktree/`，后续编辑、验证、提交、push 和受控 CLI 写操作都在该 worktree 内完成。fixed repo 只用于 `git fetch`、`git status`、快进同步、读取规则和 `git worktree add`；其中已有的并行未提交修改默认保持不动，不纳入当前任务，也不要用 reset、checkout 或删除来“清理”。 -主 worktree 同时存在脏改且落后 `origin/master` 时，必须先用 stash 保存当前脏改（包括 untracked），再执行 `git pull --ff-only origin master` 快进，随后 apply stash 并按当前 `master` 语义合并冲突或重复内容。这个 stash 是保护并行修改以便固定主 repo 回到最新 source truth，不是清理、丢弃或隐式接管并行任务；apply 后只提交当前任务明确相关的文件，其他并行修改继续保留原状。 +开始使用任何固定主/目标 worktree 时，如果发现它落后 remote/base，必须先完成 source-truth 同步再继续分析或创建任务 worktree：若工作区有脏改，先用 `git stash push -u` 保存当前脏改（包括 untracked），再执行 `git pull --ff-only ` 快进，随后 `git stash apply` 并按快进后的语义合并冲突或重复内容；若工作区 clean，则直接 `git pull --ff-only`。这个 stash 是保护并行修改以便固定主 repo 回到最新 source truth，不是清理、丢弃或隐式接管并行任务；apply 后只提交当前任务明确相关的文件，其他并行修改继续保留原状。不得在落后的固定 worktree 上继续源码分析、创建任务分支、修改代码或给 issue 写基于旧源码的结论。 + +所有源码、配置、部署脚本和运行面修复都必须在从最新 remote/base 创建的独立 `.worktree/` 中完成；固定主 worktree 不直接承载代码修改。PR 合并或等价集成进入 remote base 后，应及时回到对应固定主 worktree 执行 `git fetch` 与 `git pull --ff-only`，让下一轮 source-truth 预检、web-probe 复核、issue closeout 和新任务 worktree 都从已合并的最新源码开始。若固定主 worktree 因并行脏改不能安全快进，保留脏改并改用干净的最新 remote/base worktree 继续，不能 reset、checkout 或删除他人修改。 任务 worktree 清理前必须做语义合并核查。最低要求是：worktree clean；相关提交已经是 `origin/master` 祖先，或 `git log --left-right --cherry-pick ...origin/master` 没有 left-only 未吸收 patch；必要时再核对关键文件 diff、PR merge commit、issue closeout 和运行面验证是否对应最新 `master`。只有确认当前任务语义已经进入 `master` 或被更新实现等价替代后，才允许 `git worktree remove `；不得只因为分支落后、PR 已关闭、文件看起来相似或本地空间紧张就删除。若发现未提交文件、未推送提交、left-only patch 或语义不确定，先把应保留内容提交/合并/推送到 `master`，或记录阻塞并保留 worktree。 -文档治理是固定主 repo 保护规则的轻量例外。单纯文档、`AGENTS.md`、`docs/reference/*.md`、skill 规则、runbook、过程文档蒸馏和其他长期参考收敛不需要创建新 `.worktree` 或短生命周期 PR；应在当前主 worktree 先 `git pull --ff-only` 对齐最新 remote，再直接修改、做最小语法/diff 检查、提交并 push。该例外只覆盖文档/规则本身，不得夹带源码、配置、部署、运行面或 issue lifecycle 写操作；若主 worktree 已有并行文档修改，只提交本次明确相关文件，不能 stash、reset 或顺手合并他人修改。 +文档治理是固定主 repo 保护规则的轻量例外。单纯文档、`AGENTS.md`、`docs/reference/*.md`、skill 规则、runbook、过程文档蒸馏和其他长期参考收敛不需要创建新 `.worktree` 或短生命周期 PR；应在当前主 worktree 按上面的 stash-if-dirty + `git pull --ff-only` 对齐最新 remote 后再直接修改、做最小语法/diff 检查、提交并 push。该例外只覆盖文档/规则本身，不得夹带源码、配置、部署、运行面或 issue lifecycle 写操作；若主 worktree 已有并行文档修改，只提交本次明确相关文件，不能 reset、drop stash 或顺手合并他人修改。 允许不创建新 `.worktree` 的场景包括 P1 只读探测、运行面临时热补、上述文档/skill/长期参考轻量修改，或目标项目长期参考明确声明的直接修改例外。例外必须能解释为什么不会污染 fixed repo source truth，并且不得触碰无关并行修改；一旦需要写源码、配置、issue closeout、部署脚本、验收产物或其他高风险交付记录，立即切回独立 `.worktree`。