docs: record github cli split boundary

.agents/skills/unidesk-gh/SKILL.md

@@ -9,6 +9,14 @@ UniDesk 受控 GitHub 操作入口，底层 issue/PR REST 读写走 `bun scripts
 
 **固定入口前缀**: `cd /root/unidesk && bun scripts/cli.ts gh ...`
 
+## 实现边界
+
+GitHub 受控入口的长期架构权威是 `project-management/PJ2026-01/specs/PJ2026-010606-github-controlled-entry.md`。`scripts/src/gh.ts` 只保留兼容 re-export；新增或修改 GitHub 子命令必须落到 `scripts/src/gh/` 下对应职责模块（client/options/refs/body/issue/pr/board/attachments/escape-scan/help/index 等），不得把业务实现重新堆回根入口。
+
+拆分后的 gh 模块文件头应保留 `SPEC: PJ2026-010606 GitHub入口 <实现引用版本>` 追溯，单个模块超过 3000 行时继续拆分。PR closeout 除常规 smoke 外，应覆盖至少一条 `trans gh:/... apply-patch --dry-run` 或等价写回路径，证明虚拟正文仍走同一 guard。
+
+CLI 自检使用 `bun scripts/cli.ts check --syntax-only`、针对被改模块的 `bun --check <file>` 和必要 `gh ... --dry-run`/read smoke。不要把 `bun --check scripts/cli.ts` 当作低噪声自检；它可能执行根 help 并触发 dump。需要 scripts 类型检查时走 `bun scripts/cli.ts check --scripts-typecheck ...`，让 CLI 输出 heartbeat 和 bounded timeout 结果。
+
 ## 写入语言
 
 - Issue/PR 的正式写入一律使用中文，包括标题、正文、评论、关闭/重开说明、PR 描述、PR 评论和 merge closeout 说明。

docs/reference/cli.md

@@ -12,6 +12,8 @@ CLI 可以从 `master` 快速演进，但必须兼容 `deploy.json` 固定的 CI
 
 CI/CD、GitOps、rollout、artifact 发布、PR 合并后的 runtime lane 滚动、PipelineRun 重跑/清理、Argo refresh、运行面 retention 和 legacy runtime 退役都必须由 UniDesk CLI 的高层子命令控制。稳定入口包括 `gh pr ...`、`hwlab g14 retirement ...`、`hwlab g14 monitor-prs --lane v02|v03`、`agentrun control-plane ...`、`deploy check|plan|apply`、`ci install|status|run|publish-*|logs`、`artifact-registry ...`、`server rebuild ...`、`dev-env ...` 和后续为特定运行面补充的同级命令。原生 `kubectl`、`argo`、`tkn`、`gh`、`curl` 或临时 shell 可以作为实现细节存在于 CLI 内部，但不能作为人工或 runner 的正式控制面。
 
+GitHub 受控入口的命令用法由 `$unidesk-gh` 维护，长期模块边界以 [PJ2026-010606 GitHub入口](../../project-management/PJ2026-01/specs/PJ2026-010606-github-controlled-entry.md) 为权威。`scripts/src/gh.ts` 只保留 thin compatibility entry；具体实现必须按职责落在 `scripts/src/gh/` 子模块，新增能力不要把用法和实现细节复制到本参考文档。
+
 `trans <route> kubectl|logs|get|describe` / `tran <route> ...` 仍是 CLI 介导的低层诊断底座，用于短查询、日志尾部、只读证据和一次性故障定位。它不应承载可重复的 CI/CD 写操作：创建/删除 PipelineRun、patch Pipeline/CronJob/RBAC、annotate Argo Application、触发/回滚 rollout、修改 retention 策略、确保 SecretRef 或清理运行面资源，都应该先落成 `bun scripts/cli.ts ...` 高层子命令，再由该子命令输出结构化 dry-run、执行摘要、保护对象、后续观察命令和失败分类。
 
 当现有 CLI 对某个 CI/CD 操作缺字段、缺动作、缺状态或缺权限时，处理顺序是先补 CLI，再执行发布或治理动作。临时低层 route 写操作只允许用于一次性止血，并且必须随后把稳定能力补进 CLI 与本参考文档；不能把手工 `kubectl apply/delete/annotate`、原生 GitHub CLI、手写 REST 请求或 registry shell 脚本沉淀成长期流程。长时观察仍遵守 60 秒短查询和 submit-and-poll 语义，不用单个 `trans`/`tran` 等待完整 PipelineRun 或 Argo rollout 结束。