docs: record github issue and pr supervision rules

docs/reference/code-queue-supervision.md

@@ -41,6 +41,26 @@
 
 当一个指挥机需要突发创建大量 Code Queue 任务时，submit 默认应串行或接近串行。为了避免控制面在确认任务前被打爆，可以使用短本地锁或短延迟，尤其是在低内存主机上。目标是保持任务创建可观测且稳定，而不是最大化瞬时入队吞吐。
 
+## GitHub Issue 和 PR 使用
+
+GitHub issue 是长期需求、缺陷、阻塞和决策的 source of record。聊天上下文、Code Queue final response 和过程简报可以帮助恢复现场，但不能替代 issue 中的可检索记录。
+
+指挥官应在以下情况创建或更新 GitHub issue：
+
+- 新需求需要跨多个 Code Queue task、跨服务或跨部署阶段推进；
+- 运行中发现可复用的基础设施缺陷，例如 CLI 能力缺口、凭证注入缺口、runner 局部观测误导、部署路径不可达；
+- 任务完成但缺少远端 commit、live verification、dev/prod 部署证据等验收闭环；
+- 某个手动临时绕行暴露出长期产品化需求；
+- 战略、流程、发布线或 CI/CD 规则发生需要后续任务遵循的决策。
+
+issue 内容必须自包含，至少写清楚背景、外部收益、当前观察、需求范围、非目标、验收标准和关联任务。不要只贴聊天摘要或只写“见某任务”；Code Queue worker 可能看不到 issue，也可能无法访问完整历史，因此 issue 是人类和指挥官恢复全局态势的记录，不是 worker prompt 的替代品。
+
+如果 `gh issue create` 的 GraphQL 路径因为 token scope 或 repository metadata 查询失败，允许使用 GitHub REST API 创建 issue。CLI 或脚本应避免在日志中打印 token；失败原因应归类为 GitHub 凭证/CLI 兼容问题，而不是业务任务失败。
+
+PR 是审查型交付入口，不是所有 Code Queue 任务的默认出口。默认 master-only 交付仍按项目 Git 规则执行；当变更风险高、跨模块、需要人工审查、或任务目标明确要求 PR 交付时，worker 可以创建 PR。PR 型任务必须报告源分支、目标分支、PR URL、关联 issue、测试证据和未完成风险。禁止把 PR 当成隐藏分支仓库；PR 分支必须来自最新目标线，保持小而可审查，并在合并后确认目标分支远端 commit 可 fetch。
+
+PR 支持本身是 Code Queue 能力的一部分。实现前，指挥官可以先把“支持 PR 交付”的需求拆成独立 infra issue 和 task；在能力未完成前，不应让普通 worker 隐式依赖 PR 机制。
+
 ## 监控
 
 指挥官必须用 task 级和 queue 级证据监控 Code Queue，不能只看单一状态字段。
@@ -85,6 +105,7 @@
 只有存在明确理由时才干预。
 
 - 如果任务还在运行且 trace 或 scheduler heartbeat 新鲜，应引导而不是 interrupt。
+- 对运行中任务的引导应优先使用正式 CLI。若源码或 runtime 已有 `steer` 能力但 CLI 尚未暴露，临时通过受控 microservice proxy 调用可以作为现场恢复手段；这类临时绕行必须记录到指挥简报头部的常驻观察，并创建正式 issue 补齐 CLI 能力，避免长期依赖隐式 API。
 - 如果任务进入终态但缺少必要验收证据，应使用聚焦 continuation prompt retry 同一任务。
 - 如果任务被可复用基础设施缺陷阻塞，应把该缺陷分配给合适的空闲或低风险队列，让原业务任务等待，或在修复后 retry。
 - 如果基础设施缺陷影响 Code Queue 控制面可用性，指挥官可以执行恢复队列所需的最小受控部署，然后验证原任务能继续。

docs/report/202605/20260520_Commander.md

@@ -14,6 +14,13 @@
 - `backend-core` 和 D601 Code Queue 的生产变更默认只在 dev 验证，除非用户明确批准。
 - 简报和长期参考文档使用中文。
 
+## 常驻观察与长期建议
+
+本区只记录需要长期跟踪的指挥摩擦，不在每次轮询重复追加。
+
+- 运行中任务需要“引导优先于打断”。2026-05-20 现场发现 runtime 已有 `/api/tasks/:id/steer` 能力，但 `bun scripts/cli.ts codex --help` 未暴露正式 `codex steer`；指挥官临时通过 `microservice proxy code-queue /api/tasks/<id>/steer --method POST` 给 #16 任务注入纠偏信息，避免把 runner 内 CLI 视角误判为 D601 整体离线。长期建议：实现正式 `bun scripts/cli.ts codex steer <taskId>`，见 GitHub issue #17。
+- GitHub issue 是跨轮次需求、阻塞和决策的长期记录；PR 是审查型交付入口，不是默认出口。相关长期规则已写入 `docs/reference/code-queue-supervision.md`，后续指挥不在本报告重复展开。
+
 ## 快照 2026-05-20 04:16 UTC
 
 仓库状态：