# GitHub Pull Request

PR 工作必须使用受控 UniDesk GitHub 命令：

- review 前先用 `pr review-plan` 建立 changed-file 索引，只对需要审查的文件使用 `pr diff --file` 和有界 hunk 下钻；不得逐文件机械展开。
- 人工完整 PR 正文使用 `trans gh:/owner/repo/pr/<number> cat`；定点查找使用同一路由的 `rg <pattern>`。
- `pr view <number> --json body,...`、`--full` 和 `--raw` 只用于显式机器结构化披露；正文只在 `.data.pullRequest.body` 输出一次。
- `pr create` 默认 Next 只给有界 observe/review/preflight/status：
  - `pr view`；
  - `pr review-plan`；
  - `pr preflight`；
  - 显式 closeout 字段 status。
  默认不得提示 `preflight --full|--raw`、手工 CI/CD、mirror sync、创建 PipelineRun 或 Argo refresh。
- `pr preflight` 是可选只读诊断；`pr merge` 内部会自行执行 preflight。
- 主代理受控合并仍然允许：
  - 主代理按 `$unidesk-subagent` 完成 review 和 merge 授权判断后使用 guarded `pr merge`；
  - 不得把 `pr create` Next 限制误解成“PR 永远不能人工受控合并”。
- `pr merge --merge` 的分支处理规则：
  - 默认保留已合并的远端和本地 head branch 状态；
  - 以 `branch-preserved` 披露未删除原因；
  - 只有确认 head 是可删除的临时分支时才显式使用 `--delete-branch`；
  - 显式删除会清理 Git 已登记、分支精确匹配、非主 worktree 且状态干净的本地 worktree，不按目录名称限制；
  - 本地 closeout 仍会快进位于 PR base branch 的本地主工作区。
- 整个 PR 的授权目标、架构方向、data flow 或 source of truth 被判定错误时：
  - 未合并：通过受控 GitHub 入口关闭 PR，停止旧 writer，保留 PR/commit 作为证据；从最新目标分支创建新分支、worktree 和 PR，禁止在错误 head 上继续提交纠偏补丁；
  - 已合并：从包含该 merge 的最新目标分支创建独立 revert PR，只精确反向原 PR；先 guarded merge 回滚，再从恢复后的目标分支创建正确实现 PR；
  - 禁止把回滚和新实现混入同一 PR，也禁止用 reset、force push、覆盖式 checkout 或人工 runtime patch 冒充回滚；
  - 局部实现缺陷仍可在原未合并 PR 修正，方向性判定必须由用户最新目标、适用 SPEC 和 current/desired data flow 支撑。
- `pr merge --merge --sync-node JD01` 在支持时额外执行映射节点 source-workspace sync；当前用于 HWLAB `v0.3`。
- `--keep-branch` 保留为兼容的显式声明；只有明确需要保留本地 worktree 状态时才使用 `--skip-local-closeout`。
- 只有 ancestry 和语义吸收都明确安全时才使用 squash。
- 功能实现和 skill 在 merge 前用一个 PR 收口；TaskTree ExecutionReport 不作为仓库文件提交。遗留 MDTODO 按 `$unidesk-tasktree` 迁移。
- merge commit 与合并时间由 GitHub PR 事实和 `gh pr merge` 默认摘要保存，不要求回写 TaskTree。成功合并后不机械执行 `pr view`；只有默认输出缺少必要字段或需要定点排障时才查询。
- 只有 merge 后才产生新的运行面证据，并且用户明确要求将该证据写回 Git 时，第二个 closeout PR 才合理。

同一 PR 的 closeout 应在 merge 前写明 source branch、验证证据和残余风险。