From 6ebcc22b8f7e9c6f48fb47c184f3df4a801b5cbe Mon Sep 17 00:00:00 2001 From: Codex Date: Tue, 9 Jun 2026 10:32:21 +0000 Subject: [PATCH] docs: require task worktrees for dad-dev --- AGENTS.md | 8 ++++---- docs/reference/devops-hygiene.md | 4 ++++ 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 0e2c8c81..460efa89 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -19,11 +19,11 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台；本文 - P0: CaseRun 卡在基础设施、hwpod-node、workspace prepare、编译、下载、串口或 artifact 收集的某个步骤时，必须先把卡点拆成单步命令在同一目标运行面验证；禁止用反复全量 CaseRun 大回环替代单步定位。 - P0: 只有单步卡点已经验证通过，且需要验证完整编排、trace 和 registry 产物时，才启动一次完整 CaseRun；完整 CaseRun 仍必须按 cli-spec 异步启动、短轮询状态、收集 trace，不得把 evidence 自动评价、门禁或自动判断重新塞回流程。 -## P0 最高优先级：文档/CLI 直接主 worktree 规则 +## P0 最高优先级：固定主 repo 保护与独立 worktree 规则 -- P0: 单纯文档、AGENTS.md、docs/reference、SPEC、短连接 CLI、trans/tran/helper 这类轻量变更，禁止为了“隔离开发”新建 git worktree；必须在当前项目固定主 worktree 直接修改、提交并 push 到对应 remote 分支。 -- P0: 只有业务代码、运行面、发布链路、CI/CD、Secret、权限、数据迁移、PROD 或明确高风险改动，才按项目规则创建隔离 worktree 或走 PR；不要把重型开发流程套到文档/CLI 轻量变更上。 -- P0: 若固定主 worktree 已有「不属于这次任务的未提交修改」、其他并行未提交修改或未推送提交，默认视为可共同交付状态，一律与当前任务一起提交并直接 push；不得因此停下来询问用户是否提交，必要时使用非破坏性 rebase/autostash 或等价方式对齐 remote 后直接 push，禁止绕到新 worktree 掩盖主 worktree 状态。 +- P0: 固定主 repo 只作为 source truth 预检、fetch、status 和 worktree anchor；任何会写源码、文档、配置、issue closeout、部署脚本或验收产物的 dad-dev / post-task 工作，执行前必须从最新 remote/base 创建独立 `.worktree/` 并在其中完成修改、验证、提交和 push。 +- P0: 固定主 repo 中已有并行未提交修改时，默认保持不动，不纳入当前任务，也不得 stash、reset、checkout 或删除；当前任务通过独立 `.worktree` 隔离，除非用户最新明确要求合并提交这些并行修改。 +- P0: 只有 P1 只读探测、运行面临时热补或目标项目长期参考明确声明的直接修改例外，才允许不创建新 `.worktree`；例外不能触碰无关并行修改。长期细则见 `docs/reference/devops-hygiene.md`。 ## P0 最高优先级：可见性先修 diff --git a/docs/reference/devops-hygiene.md b/docs/reference/devops-hygiene.md index 62042a1c..f26ceacb 100644 --- a/docs/reference/devops-hygiene.md +++ b/docs/reference/devops-hygiene.md @@ -48,6 +48,10 @@ 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`；其中已有的并行未提交修改默认保持不动，不纳入当前任务，也不要用 stash、reset、checkout 或删除来“清理”。 + +允许不创建新 `.worktree` 的场景只限 P1 只读探测、运行面临时热补，或目标项目长期参考明确声明的直接修改例外。例外必须能解释为什么不会污染 fixed repo source truth，并且不得触碰无关并行修改；一旦需要写长期文档、源码、配置、issue closeout 或提交记录，立即切回独立 `.worktree`。 + 在模型 provider、API provider、硬件链路、跨平台 bridge、CLI/trans/tran 或高频工具链问题上，判定外部 blocker 前仍需完成 UniDesk 的防误判核查：确认当前 runtime config / Secret key presence / env / proxy / NO_PROXY / endpoint / args，使用实际目标运行面复现，并尽量与 UniDesk/HWLAB 成熟实现对照。用户反馈或新证据推翻 blocker 判断时，立即切回 `$dad-dev` 的现场修复闭环。 如果某个现场步骤因为 quoting、route 定位、kubeconfig、输出体积或缺少 helper 而反复痛苦，优先改进 UniDesk passthrough / CLI 并在本文件的 `Distributed Command Passthrough` 或 `docs/reference/cli.md` 中记录稳定入口，不要沉淀一批一次性 shell 菜谱。