docs: add code queue PR preflight template

AGENTS.md

@@ -43,7 +43,7 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台；本文
 - `bun scripts/cli.ts deploy check/plan/apply [--file deploy.json|--env dev|prod] [--service <id>]`：按根目录 `deploy.json` 或 `origin/master:deploy.json#environments.<env>` 的服务 repo 和 commit 期望状态校验或更新用户服务；`--env dev` 开放 D601 `backend-core` rollout、reviewed registry artifact consumers 和 D601 direct consumer validation，`findjob`/`pipeline` 是 D601 direct pull-only 样板，`met-nonlinear` dry-run blocked，`k3sctl-adapter` supervisor-only，`code-queue` prod unsupported，规则见 `docs/reference/deploy.md` 与 `docs/reference/dev-environment.md`。
 - `bun scripts/cli.ts dev-env validate [--manifest path] [--kubectl-dry-run]` / `dev-env prewarm-images`：离线校验 D601 `unidesk-dev` 生产隔离护栏和 dev workload manifests，或把开发底座基础镜像预热到 D601 原生 k3s containerd，规则见 `docs/reference/deploy.md` 与 `docs/reference/microservices.md`。
 - `bun scripts/cli.ts artifact-registry plan|render|status|health|install|deploy-backend-core|deploy-service`：管理 D601 host-managed CNCF Distribution registry，并通过短生命周期 relay 或 D601 pull/import 做 commit-pinned pull-only artifact CD；`deploy-backend-core` 是 deprecated 兼容名，`findjob`/`pipeline` 支持 D601 direct dev/prod，`met-nonlinear` 和 `k3sctl-adapter` 只给受限计划路径，`code-queue` 只支持 dev，规则见 `docs/reference/artifact-registry.md`。
-- `bun scripts/cli.ts gh auth status|issue ...|pr list|view|create|comment`：通过 REST 执行安全 GitHub issue 读写、脱敏 auth/status 诊断、body-file Markdown 写入、#24 指挥简报新增时间线 ClaudeQQ 通知、escape 扫描和 PR 创建/评论；`gh pr merge` 当前仍结构化拒绝，规则见 `docs/reference/cli.md` 和 `docs/reference/code-queue-supervision.md`。
+- `bun scripts/cli.ts gh auth status|issue ...|pr list|view|create|comment` / `bun scripts/code-queue-pr-preflight-example.ts`：通过 REST 执行安全 GitHub issue 读写、脱敏 auth/status 诊断、body-file Markdown 写入、#24 指挥简报新增时间线 ClaudeQQ 通知、escape 扫描、PR 创建/评论 dry-run 和 runner PR preflight；`gh pr merge` 当前仍结构化拒绝，规则见 `docs/reference/cli.md` 和 `docs/reference/code-queue-supervision.md`。
 - `bun scripts/cli.ts ci install/status/run/publish-backend-core/publish-user-service/run-dev-e2e/logs`：在 D601 原生 k3s 上安装和运行 Tekton CI，支持每 commit 检查、Code Queue 只读性能门禁、`CI.json` catalog 驱动的 backend-core 与 user-service commit-pinned 镜像发布和手动触发的 `origin/master:deploy.json#environments.dev` 临时 namespace e2e；catalog/producer/consumer 分工见 `docs/reference/cicd-standardization.md`，`run-dev-e2e` 的 Git 控制 runner、短 launcher 和 no-CD 边界见 `docs/reference/dev-ci-runner.md`，Tekton 规则见 `docs/reference/ci.md`。
 - `bun scripts/cli.ts codex deploy <commitId>`：旧 Code Queue 兼容部署入口已禁用，原因是它会绕过受控部署边界直连 D601 部署 Code Queue；规则见 `docs/reference/codex-deploy.md`。
 - `bun scripts/cli.ts codex submit [prompt] [--prompt-file path|--prompt-stdin] [--queue <id>]`：通过 backend-core 私有代理提交 Code Queue 任务；控制面默认走主 server `code-queue-mgr` 写入 PostgreSQL，`--dry-run` 可只检查请求体不入队，规则见 `docs/reference/cli.md`。

docs/reference/cli.md

@@ -35,6 +35,7 @@ CLI 可以从 `master` 快速演进，但必须兼容 `deploy.json` 固定的 CI
 - `gh issue update <number> --mode replace|append --body-file <file>` 是正文更新主入口，`edit` 保留为兼容别名。`replace` 用文件正文替换现有 body；`append` 先读取当前 body，再按 UTF-8 文件字节追加，保留真实换行、反引号和 Markdown 表格。更新默认拒绝字面量 `null`、空白正文和过短正文；只有真实需要写短正文时才允许显式加 `--allow-short-body`，返回 JSON 会报告该风险。#20 总看板和 #24 指挥简报是长期 body-only issue，`--body-profile auto` 会按 issue number 自动启用结构 guard：#20 必须包含 `## 看板（OPEN）`，#24 必须包含 `## 常驻观察与长期建议`；也可显式使用 `--body-profile code-queue-board|commander-brief`。`--dry-run` 不 PATCH GitHub，输出新正文长度、SHA、关键标题检查结果、字面量 `\n`、反引号、Markdown 表格和 shell 污染信号；若环境里有 `GH_TOKEN` 或 `GITHUB_TOKEN`，dry-run 还会只读抓取旧正文长度、SHA 和 `updatedAt` 作为更新前对照。正式写入可带 `--expect-updated-at <updated_at>` 或 `--expect-body-sha <sha256>`，CLI 会先读当前 issue，匹配后才 PATCH，防止旧缓存覆盖新正文。
 - `gh issue edit 24 --body-file <file> --notify-claudeqq-brief-diff [--dry-run]` 是指挥简报 #24 的通知入口。正式执行会先读取 GitHub 上 #24 旧正文并通过 #24 body profile guard，再从 `--body-file` 读取新正文；随后先 PATCH issue 主体，再把本次新增的 `## 更新 YYYY-MM-DD HH:MM 北京时间` 段落发送给 ClaudeQQ，ClaudeQQ 失败不会回滚 issue 正文，失败只体现在返回 JSON 的 `claudeqq.ok=false` 和结构化 `degradedReason`。带通知 flag 的 `--dry-run` 不 PATCH、不发送；它按新正文做发送预览，并在输出中标明非 dry-run 才会读取旧正文做可靠 diff。默认 ClaudeQQ 目标是私聊 `645275593`，默认 base URL 是 UniDesk 受控入口 `http://backend-core:8080/api/microservices/claudeqq/proxy`，可用 `UNIDESK_COMMANDER_BRIEF_CLAUDEQQ_ENABLED`、`UNIDESK_COMMANDER_BRIEF_CLAUDEQQ_BASE_URL`、`UNIDESK_COMMANDER_BRIEF_CLAUDEQQ_TARGET_TYPE`、`UNIDESK_COMMANDER_BRIEF_CLAUDEQQ_USER_ID`、`UNIDESK_COMMANDER_BRIEF_CLAUDEQQ_GROUP_ID` 和 `UNIDESK_COMMANDER_BRIEF_CLAUDEQQ_TIMEOUT_MS` 覆盖。
 - `gh issue scan-escape [--repo owner/name] [--limit N]` 只读扫描 issue 主体和 comments 中的字面量 `\n`、可疑 `\t`、shell newline escape 和 ANSI escape 字符串，输出 issue/comment id、url、kind、snippet，不自动修复。`gh pr list|view [--json ...]` 提供 REST 列表和详情，PR 字段白名单是 `body,title,state,number,url,author,head,base,draft,createdAt,updatedAt`。`gh pr create --title <title> --body-file <file>|--body <text> --base <branch> --head <branch> [--draft] [--dry-run]`、`gh pr update <number> --mode replace|append --body-file <file>|--body <text> [--title ...] [--dry-run]`、`gh pr comment create <number> --body-file <file>|--body <text> [--dry-run]`、`gh pr comment delete <commentId> [--dry-run]`、`gh pr close|reopen <number> [--dry-run]` 是 PR CRUD/生命周期入口。`pr create --dry-run` 只输出 planned operation，不访问 GitHub；非 dry-run 创建前会校验 repo、base、head 和 compare ahead 状态，成功时返回 PR number/url。`pr update --mode append` 会先读取当前 PR body 再追加正文。`gh pr delete <number>` 和 `gh pr merge` 本阶段不开放，始终结构化返回 `unsupported-command`；PR 生命周期删除语义请使用 `close`。
+- PR dry-run/probe 的最小手动序列是：`bun scripts/cli.ts gh auth status --repo pikasTech/unidesk` 只读检查 token 来源、GitHub REST egress、repo 可见性和 issue read；`bun scripts/cli.ts gh pr create --repo pikasTech/unidesk --title <title> --body-file <file> --base master --head <head> --dry-run` 检查创建计划；`bun scripts/cli.ts gh pr list --repo pikasTech/unidesk --limit 5 --json number,title,state,url,head,base` 和 `bun scripts/cli.ts gh pr view <number> --repo pikasTech/unidesk --json body,title,state,head,base` 做只读 PR 观察；`bun scripts/cli.ts gh pr comment <number> --repo pikasTech/unidesk --body-file <file> --dry-run` 检查评论计划；`bun scripts/cli.ts gh pr merge <number> --repo pikasTech/unidesk` 必须失败并返回结构化 `unsupported-command`。Code Queue runner 可用 `bun scripts/code-queue-pr-preflight-example.ts --repo pikasTech/unidesk --base master --head <head> --comment-pr <number>` 一次性跑只读 auth status 与 PR create/comment dry-run；该脚本不得输出 token 值，也不会创建、评论或 merge PR。
 - `ci install|status|run|publish-backend-core|publish-user-service|run-dev-e2e|logs` 管理 D601 原生 k3s 上的 Tekton CI。`run` 手动创建每 commit 检查和 Code Queue 只读性能门禁；`publish-backend-core` 与 `publish-user-service` 从 pushed Git commit 构建并发布 `127.0.0.1:5000/unidesk/<service>:<commit>` commit-pinned artifacts，输出 `artifactSummary`（含 `serviceId`、`sourceCommit`、`sourceRepo`、`dockerfile`、`imageRef`、`tag`、`digest`、`digestRef`），但不部署生产；`run-dev-e2e` 的 Git 控制 runner、短 launcher、host fetch 边界、临时 smoke namespace 和 no-CD 规则只在 `docs/reference/dev-ci-runner.md` 定义；Tekton CI 通用规则见 `docs/reference/ci.md`。
 - `schedule list|get|runs|run|retry-run|delete|upsert-pgdata-backup` 管理 backend-core 定时任务和运行历史。`schedule runs --limit N` 是全局历史视图，返回 `scope=global` 和 `scheduleId=null`；`schedule runs <scheduleId> --limit N` 是指定 schedule 历史视图，返回 `scope=schedule` 和对应 `scheduleId`。CLI 必须拒绝 `schedule runs 50` 这类纯数字位置参数，并提示使用 `schedule runs --limit 50`，避免把空数组误判成“没有历史 run”。`schedule run <id> --wait-ms N` 触发同一 schedule，并且即使 wait 超时也必须返回 `newRunId` 和 `observeCommand`；`schedule retry-run <failedRunId>` 只接受 failed run，从原 run 反查 `scheduleId` 后重触发同一 schedule，并输出 `originalRunId`、`scheduleId`、`newRunId` 和 `observeCommand`。
 - `codex deploy <commitId>` 是旧 Code Queue 兼容部署入口，已禁用以防止维护通道直连 D601 部署 Code Queue；当前 dev 自动化只做 `ci run-dev-e2e` smoke，不提供 Code Queue CD，详细规则见 `docs/reference/codex-deploy.md`。

docs/reference/code-queue-supervision.md

@@ -80,6 +80,48 @@ PR 是审查型交付入口，不是所有 Code Queue 任务的默认出口。
 
 PR 支持本身是 Code Queue 能力的一部分。当前 UniDesk CLI 支持 `gh pr list|view|create|update|comment create|comment delete|close|reopen`，其中 create 需要显式 `--title`、`--base`、`--head` 和正文来源，update 需要显式 PR number、正文来源和 `--mode replace|append`，comment create 需要显式 PR number 和正文来源，且推荐使用 `--body-file`。`pr create --dry-run`、`pr update --dry-run` 与 `pr comment create --dry-run` 只返回 planned operation，不创建 PR、不更新正文、不写评论；非 dry-run 创建前会校验 repo、base、head 和 compare ahead 状态，append 更新会先读取当前 PR body。`gh pr delete` 和 `gh pr merge` 仍是后续范围，本阶段没有 `--confirm` 可以启用真实 merge，也不能伪造硬删除；需要移除活跃 PR 时使用 `gh pr close`。普通 worker 不应隐式依赖未实现的 PR 合并能力；需要 PR 交付时，prompt 必须明确允许的人工或后续工具路径，并报告未覆盖范围。
 
+### PR 驱动派单模板
+
+PR 驱动是 Code Queue 协作的未来默认方向：worker 在独立 head branch 上提交，创建面向目标分支的 PR，指挥官审查后再合并并更新 issue/#20/#24。当前仍处于 runner GitHub 可达性补齐阶段；在 #19 的 runner GitHub 可达性未验收前，派单 prompt 必须自包含完整需求、约束、写入范围和验收标准，不能只贴 GitHub issue 链接。issue URL 只能作为辅助引用。
+
+PR 型派单 prompt 至少包含以下字段：
+
+- `目标 issue`：写明 issue 编号、URL 和本次任务要关闭或推进的验收点；不要假设 runner 能读取 issue。
+- `目标分支`：明确 `master` 或经批准的维护分支；普通开发集成使用 `master`。
+- `head branch`：使用可追踪命名，例如 `code-queue/issue-35-pr-dry-run-probe`、`code-queue/issue-<number>-<short-topic>` 或包含 task id 的等价短名；head branch 必须从最新 `origin/<目标分支>` 创建。
+- `禁止动作`：禁止直接 push 目标分支，禁止 merge PR，禁止改 release/v1 运行态服务，禁止输出 token，禁止跑本任务未要求的重型 check/e2e/Playwright。
+- `必须动作`：提交前运行轻量自测；push head branch；创建面向目标分支的 PR；PR body 写清关联 issue、修改文件、验证命令和风险；若创建 PR 前需要探测，先运行只读或 dry-run preflight。
+- `final response 字段`：实际分支、目标分支、head branch、PR URL、远端 head commit、是否已创建 PR、是否未 merge、修改文件、验证命令和结果、遗留风险；如果 PR 未能创建，报告结构化原因和 runnerDisposition。
+
+PR 型 prompt 可直接嵌入以下 Git 指令约束：
+
+```text
+Git/PR 交付要求：
+- 目标分支：master。
+- 从最新 origin/master 创建 head branch：code-queue/issue-<number>-<short-topic>。
+- 不得直接 push master 或 release/v1。
+- 必须 push head branch 并创建 PR 到 master；不得 merge PR。
+- 创建 PR 前先运行只读/dry-run preflight，确认 GH_TOKEN/GITHUB_TOKEN、GitHub egress 和 repo 可见性，不得打印 token。
+- final response 必须报告 head branch、PR URL、远端 head commit、修改文件、验证命令、是否未 merge。
+```
+
+Runner preflight 示例：
+
+```bash
+bun scripts/code-queue-pr-preflight-example.ts --repo pikasTech/unidesk --base master --head code-queue/issue-35-pr-dry-run-probe --comment-pr 1
+```
+
+该脚本只读调用 `gh auth status`，并执行 `gh pr create --dry-run` 与 `gh pr comment --dry-run`。它检查 `GH_TOKEN/GITHUB_TOKEN` 是否存在、GitHub REST egress 是否可达、repo 是否可见，并且只输出 token 来源和存在性，不输出 token 值。`--comment-pr` 只是 dry-run 计划中的 PR number，不会写评论。
+
+指挥官审查 checklist：
+
+- PR base 是声明的目标分支，head branch 命名可追踪，远端 head commit 可 fetch。
+- diff 只覆盖派单 ownership，未混入 release/v1 运行态服务或无关 dirty worktree。
+- PR body 和 final response 都包含关联 issue、修改文件、验证证据、未完成风险和未 merge 状态。
+- contract/dry-run 证据覆盖本次 PR 能力：`pr create --dry-run`、`pr list/view`、`pr comment --dry-run`，并确认 `gh pr merge` 返回结构化 unsupported。
+- 没有 token、凭证、临时日志或构建产物进入 commit、PR body 或评论。
+- 合并前由指挥官审查并决定是否 merge；合并后再验证目标分支远端 commit 可见，并按态势更新 issue/#20/#24。
+
 ## 监控
 
 指挥官必须用 task 级和 queue 级证据监控 Code Queue，不能只看单一状态字段。

scripts/code-queue-pr-preflight-example.ts

@@ -0,0 +1,229 @@
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+type JsonRecord = Record<string, unknown>;
+
+interface CliResult {
+  status: number | null;
+  ok: boolean;
+  json: JsonRecord | null;
+  stdoutBytes: number;
+  stderrBytes: number;
+  stdoutPreview?: string;
+  stderrPreview?: string;
+}
+
+const DEFAULT_REPO = "pikasTech/unidesk";
+const DEFAULT_BASE = "master";
+const DEFAULT_HEAD = "code-queue/pr-preflight-example";
+const DEFAULT_COMMENT_PR = "1";
+const PREVIEW_CHARS = 400;
+
+function optionValue(args: string[], name: string, defaultValue: string): string {
+  const index = args.indexOf(name);
+  if (index === -1) return defaultValue;
+  const value = args[index + 1];
+  if (value === undefined || value.length === 0 || value.startsWith("--")) throw new Error(`${name} requires a value`);
+  return value;
+}
+
+function secrets(): string[] {
+  return [process.env.GH_TOKEN, process.env.GITHUB_TOKEN].filter((value): value is string => value !== undefined && value.length > 0);
+}
+
+function redactText(text: string): string {
+  let redacted = text;
+  for (const secret of secrets()) {
+    redacted = redacted.split(secret).join("<redacted>");
+  }
+  return redacted;
+}
+
+function redactUnknown(value: unknown): unknown {
+  if (typeof value === "string") return redactText(value);
+  if (Array.isArray(value)) return value.map(redactUnknown);
+  if (typeof value === "object" && value !== null) {
+    const entries = Object.entries(value).map(([key, entry]) => [key, redactUnknown(entry)]);
+    return Object.fromEntries(entries);
+  }
+  return value;
+}
+
+function preview(text: string): string {
+  return redactText(text.length > PREVIEW_CHARS ? `${text.slice(0, PREVIEW_CHARS)}...` : text);
+}
+
+function runCli(args: string[]): CliResult {
+  const result = spawnSync("bun", ["scripts/cli.ts", ...args], {
+    cwd: process.cwd(),
+    env: process.env,
+    encoding: "utf8",
+    timeout: 30_000,
+  });
+  const stdout = result.stdout ?? "";
+  const stderr = result.stderr ?? "";
+  let json: JsonRecord | null = null;
+  try {
+    json = redactUnknown(JSON.parse(stdout) as unknown) as JsonRecord;
+  } catch {
+    json = null;
+  }
+  return {
+    status: result.status,
+    ok: result.status === 0 && json?.ok === true,
+    json,
+    stdoutBytes: Buffer.byteLength(stdout),
+    stderrBytes: Buffer.byteLength(stderr),
+    ...(json === null && stdout.length > 0 ? { stdoutPreview: preview(stdout) } : {}),
+    ...(stderr.length > 0 ? { stderrPreview: preview(stderr) } : {}),
+  };
+}
+
+function dataOf(result: CliResult): JsonRecord | null {
+  const data = result.json?.data;
+  return typeof data === "object" && data !== null && !Array.isArray(data) ? data as JsonRecord : null;
+}
+
+function envTokenProbe(): JsonRecord {
+  if (process.env.GH_TOKEN && process.env.GH_TOKEN.length > 0) return { ok: true, present: true, source: "GH_TOKEN" };
+  if (process.env.GITHUB_TOKEN && process.env.GITHUB_TOKEN.length > 0) return { ok: true, present: true, source: "GITHUB_TOKEN" };
+  return {
+    ok: false,
+    present: false,
+    source: null,
+    message: "Runner PR workflow requires GH_TOKEN or GITHUB_TOKEN in the environment; token values must never be printed.",
+  };
+}
+
+function dryRunSummary(result: CliResult): JsonRecord {
+  const data = dataOf(result);
+  return {
+    ok: result.ok,
+    status: result.status,
+    stdoutBytes: result.stdoutBytes,
+    stderrBytes: result.stderrBytes,
+    ...(data === null ? {} : {
+      command: data.command,
+      dryRun: data.dryRun,
+      planned: data.planned,
+      repo: data.repo,
+      base: data.base,
+      head: data.head,
+      issueNumber: data.issueNumber,
+      bodyChars: data.bodyChars,
+      request: data.request,
+    }),
+    ...(result.stdoutPreview === undefined ? {} : { stdoutPreview: result.stdoutPreview }),
+    ...(result.stderrPreview === undefined ? {} : { stderrPreview: result.stderrPreview }),
+  };
+}
+
+function main(): void {
+  const args = process.argv.slice(2);
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(`${JSON.stringify({
+      ok: true,
+      command: "code-queue-pr-preflight-example",
+      usage: "bun scripts/code-queue-pr-preflight-example.ts [--repo owner/name] [--base branch] [--head branch] [--comment-pr number]",
+      note: "Read-only/dry-run runner preflight. It checks GH_TOKEN/GITHUB_TOKEN presence, GitHub REST egress and repo visibility through gh auth status, then exercises PR create/comment dry-run paths without creating or merging a PR.",
+    }, null, 2)}\n`);
+    return;
+  }
+
+  const repo = optionValue(args, "--repo", DEFAULT_REPO);
+  const base = optionValue(args, "--base", DEFAULT_BASE);
+  const head = optionValue(args, "--head", process.env.CODE_QUEUE_HEAD_BRANCH ?? DEFAULT_HEAD);
+  const commentPr = optionValue(args, "--comment-pr", DEFAULT_COMMENT_PR);
+  const tmp = mkdtempSync(join(tmpdir(), "unidesk-pr-preflight-"));
+  const bodyFile = join(tmp, "body.md");
+  writeFileSync(bodyFile, [
+    "# Code Queue PR preflight",
+    "",
+    "This file is used only for local dry-run planning.",
+    "",
+  ].join("\n"), "utf8");
+
+  try {
+    const token = envTokenProbe();
+    const auth = runCli(["gh", "auth", "status", "--repo", repo]);
+    const createDryRun = runCli([
+      "gh",
+      "pr",
+      "create",
+      "--repo",
+      repo,
+      "--title",
+      "Code Queue PR preflight dry run",
+      "--body-file",
+      bodyFile,
+      "--base",
+      base,
+      "--head",
+      head,
+      "--dry-run",
+    ]);
+    const commentDryRun = runCli([
+      "gh",
+      "pr",
+      "comment",
+      commentPr,
+      "--repo",
+      repo,
+      "--body-file",
+      bodyFile,
+      "--dry-run",
+    ]);
+    const authData = dataOf(auth);
+    const ok = token.ok === true && auth.ok && createDryRun.ok && commentDryRun.ok;
+    process.stdout.write(`${JSON.stringify({
+      ok,
+      command: "code-queue-pr-preflight-example",
+      repo,
+      base,
+      head,
+      commentPr,
+      checks: {
+        envToken: token,
+        githubAuthStatus: {
+          ok: auth.ok,
+          status: auth.status,
+          stdoutBytes: auth.stdoutBytes,
+          stderrBytes: auth.stderrBytes,
+          ...(authData === null ? {} : {
+            degraded: authData.degraded,
+            token: authData.token,
+            probes: authData.probes,
+            restFallback: authData.restFallback,
+          }),
+          ...(auth.stdoutPreview === undefined ? {} : { stdoutPreview: auth.stdoutPreview }),
+          ...(auth.stderrPreview === undefined ? {} : { stderrPreview: auth.stderrPreview }),
+        },
+        prCreateDryRun: dryRunSummary(createDryRun),
+        prCommentDryRun: dryRunSummary(commentDryRun),
+      },
+      safety: {
+        writesRemote: false,
+        createsPullRequest: false,
+        commentsPullRequest: false,
+        mergesPullRequest: false,
+        tokenValuesPrinted: false,
+      },
+    }, null, 2)}\n`);
+    if (!ok) process.exitCode = 1;
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+try {
+  main();
+} catch (error) {
+  process.stdout.write(`${JSON.stringify({
+    ok: false,
+    command: "code-queue-pr-preflight-example",
+    error: redactText(error instanceof Error ? error.message : String(error)),
+  }, null, 2)}\n`);
+  process.exitCode = 1;
+}

scripts/gh-cli-pr-contract-test.ts

@@ -7,16 +7,16 @@ import { tmpdir } from "node:os";
 
 type JsonRecord = Record<string, unknown>;
 
-function assertCondition(condition: unknown, message: string, detail: JsonRecord = {}): void {
+function assertCondition(condition: unknown, message: string, detail: unknown = {}): void {
   if (!condition) throw new Error(`${message}: ${JSON.stringify(detail)}`);
 }
 
-function runCli(args: string[], env: Record<string, string> = {}): Promise<{ status: number | null; stdout: string; stderr: string; json: JsonRecord | null }> {
+function runBun(args: string[], env: Record<string, string> = {}): Promise<{ status: number | null; stdout: string; stderr: string; json: JsonRecord | null }> {
   return new Promise((resolve, reject) => {
-    const child = spawn("bun", ["scripts/cli.ts", ...args], {
-    cwd: process.cwd(),
-    env: { ...process.env, ...env },
-  });
+    const child = spawn("bun", args, {
+      cwd: process.cwd(),
+      env: { ...process.env, ...env },
+    });
     const stdoutChunks: Buffer[] = [];
     const stderrChunks: Buffer[] = [];
     child.stdout.on("data", (chunk) => stdoutChunks.push(Buffer.from(chunk)));
@@ -40,6 +40,10 @@ function runCli(args: string[], env: Record<string, string> = {}): Promise<{ sta
   });
 }
 
+function runCli(args: string[], env: Record<string, string> = {}): Promise<{ status: number | null; stdout: string; stderr: string; json: JsonRecord | null }> {
+  return runBun(["scripts/cli.ts", ...args], env);
+}
+
 interface MockRequest {
   method: string;
   url: string;
@@ -79,10 +83,18 @@ async function startMockGitHub(): Promise<{ baseUrl: string; requests: MockReque
   const server = createServer(async (req, res) => {
     const body = await collectBody(req);
     requests.push({ method: req.method ?? "", url: req.url ?? "", body });
+    if (req.method === "GET" && req.url === "/rate_limit") {
+      sendJson(res, 200, { resources: { core: { limit: 5000, remaining: 4999 } } });
+      return;
+    }
     if (req.method === "GET" && req.url === "/repos/pikasTech/unidesk") {
       sendJson(res, 200, { id: 1, full_name: "pikasTech/unidesk", private: true, default_branch: "master", permissions: { pull: true, push: true } });
       return;
     }
+    if (req.method === "GET" && req.url === "/repos/pikasTech/unidesk/issues?per_page=1&state=all") {
+      sendJson(res, 200, []);
+      return;
+    }
     if (req.method === "GET" && req.url === "/repos/pikasTech/unidesk/pulls?state=all&per_page=4") {
       sendJson(res, 200, [pullRequest]);
       return;
@@ -154,6 +166,34 @@ export async function runGhCliPrContract(): Promise<JsonRecord> {
     assertCondition(pullRequest.number === 42 && pullRequest.url === "https://github.com/pikasTech/unidesk/pull/42", "pr view should expose PR details", viewData);
     const selected = viewData.json as JsonRecord;
     assertCondition(selected.body === "PR body" && selected.title === "contract PR", "pr view --json should select fields", viewData);
+
+    const preflight = await runBun([
+      "scripts/code-queue-pr-preflight-example.ts",
+      "--repo",
+      "pikasTech/unidesk",
+      "--base",
+      "master",
+      "--head",
+      "feature/pr-contract",
+      "--comment-pr",
+      "42",
+    ], env);
+    assertCondition(preflight.status === 0, "PR preflight example should succeed against mock GitHub", preflight.json ?? { stdout: preflight.stdout });
+    assertCondition(preflight.json?.ok === true, "PR preflight example should report ok=true", preflight.json ?? {});
+    assertCondition(!preflight.stdout.includes("contract-token"), "PR preflight example must not print token values", { stdout: preflight.stdout });
+    assertCondition(typeof preflight.json?.checks === "object" && preflight.json.checks !== null && !Array.isArray(preflight.json.checks), "PR preflight should expose checks", preflight.json ?? {});
+    const preflightChecks = preflight.json?.checks as JsonRecord;
+    const envToken = preflightChecks.envToken as JsonRecord;
+    assertCondition(envToken.present === true && envToken.source === "GH_TOKEN", "PR preflight should require env token source", envToken);
+    const authStatus = preflightChecks.githubAuthStatus as JsonRecord;
+    assertCondition(authStatus.ok === true, "PR preflight should prove GitHub REST egress and repo visibility", authStatus);
+    const preflightCreate = preflightChecks.prCreateDryRun as JsonRecord;
+    const preflightComment = preflightChecks.prCommentDryRun as JsonRecord;
+    assertCondition(preflightCreate.ok === true && preflightCreate.dryRun === true && preflightCreate.planned === true, "PR preflight create must stay dry-run", preflightCreate);
+    assertCondition(preflightComment.ok === true && preflightComment.dryRun === true && preflightComment.planned === true, "PR preflight comment must stay dry-run", preflightComment);
+    assertCondition(mock.requests.some((request) => request.method === "GET" && request.url === "/rate_limit"), "PR preflight should probe REST egress", mock.requests);
+    assertCondition(mock.requests.some((request) => request.method === "GET" && request.url === "/repos/pikasTech/unidesk"), "PR preflight should probe repo visibility", mock.requests);
+    assertCondition(mock.requests.every((request) => request.method === "GET"), "initial mock phase should remain read-only", mock.requests);
   } finally {
     await mock.close();
   }

scripts/src/check.ts

@@ -284,6 +284,8 @@ export function runChecks(config: UniDeskConfig, options: CheckOptions = default
       fileItem("scripts/src/ci.ts"),
       fileItem("scripts/src/e2e.ts"),
       fileItem("scripts/code-queue-prompt-observation-test.ts"),
+      fileItem("scripts/gh-cli-pr-contract-test.ts"),
+      fileItem("scripts/code-queue-pr-preflight-example.ts"),
       fileItem("scripts/schedule-cli-contract-test.ts"),
       fileItem("scripts/src/artifact-registry.ts"),
       fileItem("src/components/microservices/k3sctl-adapter/k3s/ci/unidesk-ci.pipeline.yaml"),
@@ -303,6 +305,7 @@ export function runChecks(config: UniDeskConfig, options: CheckOptions = default
     items.push(commandItem("code-queue:oa-publisher-degraded-visible", ["bun", "scripts/code-queue-liveness-diagnostics-test.ts", "--only", "code-queue:oa-publisher-degraded-visible"], 30_000));
     items.push(commandItem("baidu-netdisk:artifact-guard-contract", ["bun", "scripts/baidu-netdisk-artifact-guard-contract-test.ts"], 30_000));
     items.push(commandItem("schedule:cli-contract", ["bun", "scripts/schedule-cli-contract-test.ts"], 30_000));
+    items.push(commandItem("gh:pr-contract", ["bun", "scripts/gh-cli-pr-contract-test.ts"], 30_000));
   } else {
     items.push(skippedItem("typescript:scripts", "scripts TypeScript typecheck is opt-in", "--scripts-typecheck or --full"));
     items.push(skippedItem("code-queue:prompt-observation-contract", "prompt observation contract is opt-in with script checks", "--scripts-typecheck or --full"));
@@ -311,6 +314,7 @@ export function runChecks(config: UniDeskConfig, options: CheckOptions = default
     items.push(skippedItem("code-queue:liveness-diagnostics-fixtures", "Code Queue liveness diagnostics fixtures are opt-in with script checks", "--scripts-typecheck or --full"));
     items.push(skippedItem("baidu-netdisk:artifact-guard-contract", "Baidu Netdisk artifact guard contract is opt-in with script checks", "--scripts-typecheck or --full"));
     items.push(skippedItem("schedule:cli-contract", "Schedule CLI contract is opt-in with script checks", "--scripts-typecheck or --full"));
+    items.push(skippedItem("gh:pr-contract", "GitHub PR CLI contract is opt-in with script checks", "--scripts-typecheck or --full"));
   }
   if (options.logs) {
     items.push(unifiedLogRotationItem());