docs: allow direct reference doc updates

2026-06-13 11:06:22 +00:00
parent 04020af4d4
commit 3d47a86cbf
3 changed files with 9 additions and 6 deletions
@@ -165,7 +165,7 @@ GitHub issue 是长期需求、缺陷、阻塞和决策的 source of record。

 issue 内容必须自包含，至少写清楚背景、外部收益、当前观察、需求范围、非目标、验收标准和关联任务。不要只贴聊天摘要或只写“见某任务”；Code Queue worker 可能看不到 issue，也可能无法访问完整历史，因此 issue 是人类和指挥官恢复全局态势的记录，不是 worker prompt 的替代品。

-长任务和跨回合排障应把专题 issue 的评论区作为进展锚点。调查结论、细化方案、阶段性修复、rollout 状态、阻塞原因、复测 trace、最终验收和后续风险都应追加到同一个专题 issue 评论中，并引用相关 PR、commit、job、trace 或 runtime revision；正文只保留稳定背景、范围、验收标准和当前摘要，不写成每一步流水账。上下文压缩、切换指挥官或恢复中断后，先读取专题 issue 最新评论，再继续执行，避免只依赖聊天记忆或本地临时文件。写评论必须使用 `bun scripts/cli.ts gh issue comment create ... --body-file <file|->`，长正文不得用 shell 参数拼接。
+长任务和跨回合排障应把专题 issue 的评论区作为进展锚点。调查结论、细化方案、阶段性修复、rollout 状态、阻塞原因、复测 trace、最终验收和后续风险都应追加到同一个专题 issue 评论中，并引用相关 PR、commit、job、trace 或 runtime revision；正文只保留稳定背景、范围、验收标准和当前摘要，不写成每一步流水账。每次从上下文压缩、切换指挥官、resume 或中断恢复后，都必须先读取专题 issue 最新评论；只要任务已有或应有专题 issue，继续任何实质操作前还必须先写一条“恢复锚点”评论，说明当前北京时间、已完成内容、当前运行 / PR / commit / PipelineRun、剩余下一步和阻塞点。即使压缩摘要看起来完整、状态未变化或 agent session memory 可用，也不得跳过恢复锚点评论。写评论必须使用 `bun scripts/cli.ts gh issue comment create ... --body-file <file|->`，长正文不得用 shell 参数拼接。

 如果某个 worker 任务需要依赖 GitHub issue 内容，但 runner 的 issue 可达性尚未被单独验证，指挥官不能默认 worker 已能读取该 issue。此时 worker prompt 必须直接内嵌完整需求、约束和验收点，issue URL 只能作为辅助引用。若要把 issue 作为任务输入源，先单独做可达性探测，再决定是否把 issue 作为常规前置条件。

@@ -48,9 +48,11 @@ 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/<task>`，后续编辑、验证、提交、push 和受控 CLI 写操作都在该 worktree 内完成。fixed repo 只用于 `git fetch`、`git status`、读取规则和 `git worktree add`；其中已有的并行未提交修改默认保持不动，不纳入当前任务，也不要用 stash、reset、checkout 或删除来“清理”。
+固定主 repo 是 source truth anchor，不是源码/运行面 scratch 区。会产生源码、配置、issue closeout、部署脚本、验收产物或高风险 dad-dev / post-task 交付的工作，执行前必须先从目标 fixed repo 的最新 remote/base 创建任务专属 `.worktree/<task>`，后续编辑、验证、提交、push 和受控 CLI 写操作都在该 worktree 内完成。fixed repo 只用于 `git fetch`、`git status`、读取规则和 `git worktree add`；其中已有的并行未提交修改默认保持不动，不纳入当前任务，也不要用 stash、reset、checkout 或删除来“清理”。

-允许不创建新 `.worktree` 的场景只限 P1 只读探测、运行面临时热补，或目标项目长期参考明确声明的直接修改例外。例外必须能解释为什么不会污染 fixed repo source truth，并且不得触碰无关并行修改；一旦需要写长期文档、源码、配置、issue closeout 或提交记录，立即切回独立 `.worktree`。
+文档治理是固定主 repo 保护规则的轻量例外。单纯文档、`AGENTS.md`、`docs/reference/*.md`、skill 规则、runbook、过程文档蒸馏和其他长期参考收敛不需要创建新 `.worktree` 或短生命周期 PR；应在当前主 worktree 先 `git pull --ff-only` 对齐最新 remote，再直接修改、做最小语法/diff 检查、提交并 push。该例外只覆盖文档/规则本身，不得夹带源码、配置、部署、运行面或 issue lifecycle 写操作；若主 worktree 已有并行文档修改，只提交本次明确相关文件，不能 stash、reset 或顺手合并他人修改。
+
+允许不创建新 `.worktree` 的场景包括 P1 只读探测、运行面临时热补、上述文档/skill/长期参考轻量修改，或目标项目长期参考明确声明的直接修改例外。例外必须能解释为什么不会污染 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` 的现场修复闭环。