Merge pull request #146 from pikasTech/feat/commander-prompt-lint

feat(commander): add GPT prompt boundary lint

AGENTS.md

@@ -64,7 +64,7 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台；本文
 - `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 auth-broker contract|health --dry-run|credential-request --dry-run|pr-preflight --dry-run`：查看 Auth Broker P0 Rust skeleton 与 CLI adapter contract，runner 无 `GH_TOKEN`/`GITHUB_TOKEN` 时返回结构化 `auth-missing`/`broker-needed`，不读取或打印 token 值，规则见 `docs/reference/auth-broker.md`。
 - `bun scripts/cli.ts gh preflight|auth status|issue ...|pr list|files|diff --stat|read|view|preflight|closeout|create|edit|update|comment` / `bun scripts/code-queue-pr-preflight-example.ts`：通过 REST 执行安全 GitHub issue 读写、脱敏 auth/status 诊断、body-file Markdown 写入、当日滚动简报时间线 ClaudeQQ 通知、escape 扫描、只读 cleanup-plan 和 #20 board-audit、PR changed-file/stat summary、PR 创建/评论 dry-run、REST-only 低噪声 PR title/body 编辑、PR 收口元数据观察（含 merged/closed 区分与 merge commit）、低噪声 PR 收口 preflight 与 runner PR preflight；`gh issue/pr read|view` 支持 `owner/repo#number` shorthand，`--raw|--full` 是显式完整披露别名，`gh pr diff` 仅支持 `--stat` 紧凑 JSON，`gh pr merge` 当前仍结构化拒绝但普通 PR 可按任务边界用 repo-owned GitHub 路径收口，规则见 `docs/reference/cli.md` 和 `docs/reference/code-queue-supervision.md`。
-- `bun scripts/cli.ts commander contract|plan --dry-run|smoke --dry-run|approval request --dry-run`：查看 host Codex 指挥官直管微服务 skeleton 的 source/contract、无 daemon smoke 验证计划、.state/commander/ 状态模型、trace summary 聚合和 ClaudeQQ 高风险请示草案；当前只返回 dry-run 计划和 backend-core `microservice proxy claudeqq` 授权后候选命令，不接 live bridge、不接管人工指挥官，不发送消息，规则见 `docs/reference/host-codex-commander.md`。
+- `bun scripts/cli.ts commander contract|plan --dry-run|smoke --dry-run|approval request --dry-run|prompt-lint --kind gpt55-pr`：查看 host Codex 指挥官直管微服务 skeleton 的 source/contract、无 daemon smoke 验证计划、.state/commander/ 状态模型、trace summary 聚合、ClaudeQQ 高风险请示草案和 GPT-5.5 PR prompt 边界辅助 lint；当前只返回 dry-run 计划和 backend-core `microservice proxy claudeqq` 授权后候选命令，不接 live bridge、不接管人工指挥官，不发送消息，`prompt-lint` 不作为业务 PR 门禁也不改变 `codex submit` 默认行为，规则见 `docs/reference/host-codex-commander.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 prompt-lint [prompt|--prompt-file path|--prompt-stdin]` / `codex submit [prompt] [--prompt-file path|--prompt-stdin] [--queue <id>]` / `codex pr-preflight [--remote]`：`prompt-lint` 在派发/steer 前 dry-run 检查 runner prompt 的 DEV 测试授权分级（`read-only`/`live-read`/`live-mutating`）且不回显 prompt；`submit --dry-run` 同时给出 MiniMax/GPT/人工路由建议、该 lint 结果和 requested/effective execution mode；真实提交成功只返回写入确认、task id、服务级 runnerPermissions 和后续查看命令，不回显 prompt；`pr-preflight` 只读检查 D601 scheduler/runner 的 GitHub token、egress 和 PR 能力，PR 型派单前必须使用，规则见 `docs/reference/cli.md` 和 `docs/reference/code-queue-supervision.md`。

docs/reference/cli.md

@@ -30,7 +30,7 @@ CLI 可以从 `master` 快速演进，但必须兼容 `deploy.json` 固定的 CI
 - `dev-env validate [--manifest path] [--kubectl-dry-run]` 离线校验 D601 `unidesk-dev` namespace、dev PostgreSQL 底座和 dev workload manifest。默认检查 `src/components/microservices/k3sctl-adapter/k3s/dev/unidesk-dev-foundation.k8s.yaml`；也可显式校验 `src/components/microservices/k3sctl-adapter/k3s/dev/unidesk-dev-core.k8s.yaml` 或 `src/components/microservices/k3sctl-adapter/k3s/dev/unidesk-dev-code-queue.k8s.yaml`。所有 namespaced 对象必须只落到 `unidesk-dev`，foundation manifest 必须包含 `postgres-dev` StatefulSet/Service、dev secret/config、迁移 Job 和 DB URL guard，core manifest 必须包含 `backend-core-dev`/`frontend-dev` Deployment/Service，Code Queue dev manifest 必须包含 `code-queue-scheduler-dev`、`code-queue-read-dev`、`code-queue-write-dev`、dev provider egress proxy，以及只读挂载宿主 `/home/ubuntu/.agents/skills` 到容器 `/root/.agents/skills` 的 `skills-dir` volume。加 `--kubectl-dry-run` 时额外以 `KUBECONFIG=/etc/rancher/k3s/k3s.yaml` 执行 `kubectl apply --dry-run=client --validate=false -f <manifest>`，仍不 apply 资源；默认 `docker-desktop` kubeconfig 不得作为 D601 dry-run 目标。
 - `dev-env prewarm-images [--image image] [--provider-id D601] [--no-pull] [--proxy-url URL] [--pull-timeout-ms N] [--dry-run]` 创建异步 job，通过 UniDesk SSH 维护桥在 D601 上把开发底座依赖镜像从 Docker 缓存导入原生 k3s containerd。默认镜像是 `postgres:16-alpine` 和 `rancher/mirrored-library-busybox:1.36.1`，用于避免 `postgres-dev` 与 local-path helper pod 卡在外部 registry 拉取。该命令固定验证 `/etc/rancher/k3s/k3s.yaml` 指向的 native k3s 上下文，并输出 `dev_env_containerd_image_ready=...` 作为成功判据；它不 apply manifest、不修改生产 `unidesk` namespace。
 - `artifact-registry plan|render|status|health|install|deploy-backend-core|deploy-service` 管理 D601 host-managed CNCF Distribution registry 的声明、安装、只读检查和 pull-only artifact CD。该 registry 固定为 D601 loopback `127.0.0.1:5000`，由 systemd + Docker Compose 管理，位于 native k3s 故障域外；`deploy-service` 只拉取 CI 已发布的 commit-pinned 镜像、retag/recreate 或导入 native k3s，并做 live commit 验证，不构建 runtime source。`deploy-backend-core` 是 deprecated 兼容名，标准 backend-core prod CD 入口是 `deploy apply --env prod --service backend-core`。长期规则见 `docs/reference/artifact-registry.md`。
-- `commander contract|plan --dry-run|smoke --dry-run|approval request --dry-run` 是 host Codex 指挥官直管微服务 skeleton 入口。当前命令返回 `phase=source-contract`、service/API/state/bridge/prompt/trace/#20/#46/ClaudeQQ 审批边界、.state/commander/ 状态模型、dev 无 daemon smoke contract 和 dry-run 计划，服务骨架只提供本地 `/health`、`/api/commander/contract`、状态读写、trace summary 聚合和 approval draft preview，不接 live bridge、不注入 prompt、不发送 ClaudeQQ。`approval request --dry-run` 会生成 200 字以内中文纯文本 ClaudeQQ 审批草案、`notification-path-unavailable` blocker 和授权后唯一可用的 `bun scripts/cli.ts microservice proxy claudeqq /api/push/text --method POST --body-json '<payload>' --raw` 命令；不得提示使用本机 ClaudeQQ skill、powershell 或本地 server。`plan`、`smoke` 与 `approval request` 必须带 `--dry-run`；缺少时返回 `error=dry-run-required`。长期规则见 `docs/reference/host-codex-commander.md`。
+- `commander contract|plan --dry-run|smoke --dry-run|approval request --dry-run|prompt-lint --kind gpt55-pr` 是 host Codex 指挥官直管微服务 skeleton 入口。当前命令返回 `phase=source-contract`、service/API/state/bridge/prompt/trace/#20/#46/ClaudeQQ 审批边界、.state/commander/ 状态模型、dev 无 daemon smoke contract、dry-run 计划和 GPT-5.5 PR prompt 边界辅助 lint，不接 live bridge、不注入 prompt、不发送 ClaudeQQ。`approval request --dry-run` 会生成 200 字以内中文纯文本 ClaudeQQ 审批草案、`notification-path-unavailable` blocker 和授权后唯一可用的 `bun scripts/cli.ts microservice proxy claudeqq /api/push/text --method POST --body-json '<payload>' --raw` 命令；不得提示使用本机 ClaudeQQ skill、powershell 或本地 server。`prompt-lint` 支持 `--prompt-file` 与 `--stdin`，输出 `ok`、`missingClauses`、`riskLevel`、`suggestedPatchSnippet` 且不回显完整 prompt；它是 commander 辅助检查，不是业务 PR 门禁，也不改变 `codex submit` 默认行为。`plan`、`smoke` 与 `approval request` 必须带 `--dry-run`；缺少时返回 `error=dry-run-required`。长期规则见 `docs/reference/host-codex-commander.md`。
 - `gh auth status [--repo owner/name]` 探测 GitHub 操作前置条件并输出脱敏 JSON：是否存在 `gh` binary、是否存在 `GH_TOKEN`/`GITHUB_TOKEN` 或可用 `gh auth token` fallback、REST API 是否可达、目标 repo 是否可见、issue 是否可读。degraded reason 必须归类为 `missing-binary`、`missing-token`、`auth-failed`、`github-transient`、`network-proxy-failed`、`permission-denied`、`repo-not-found`、`repo-forbidden`、`issue-not-found`、`pr-not-found`、`scope-insufficient`、`validation-failed`、`invalid-response` 或 `unsupported-command`，不得打印 token；失败对象必须包含 `runnerDisposition=infra-blocked|business-failed`，runner 应优先用该字段分流。`github-transient` 表示 GitHub DNS/API 连接在收到 HTTP 状态前失败，输出应带 `retryable=true` 或等价 commander action；这不是缺 token、认证失败、权限不足或 PR 语义失败。
 - `codex prompt-lint [prompt|--prompt-file path|--prompt-stdin]` 是派发/steer 前的本地 dry-run prompt lint。它只读取 prompt 文本，返回 `dryRun=true`、`mutation=false`、`declaredClass`、`effectiveClass`、`requiredClass`、`dispatchDisposition`、缺失或矛盾项和有界 evidence，不访问 live service、不提交任务、不打印完整 prompt。分级固定为 `read-only`、`live-read`、`live-mutating`；未声明时按 `read-only` 处理。`codex submit --dry-run` 与 `codex steer --dry-run` 会嵌入同一 `promptLint` 结果，帮助指挥官在 dispatch/steer 前发现缺失或矛盾的 live mutation 授权。长期规则见 `docs/reference/code-queue-supervision.md` 的 DEV 测试授权分级。
 - `gh issue list [--state open|closed|all] [--limit N] [--repo owner/name] [--json number,title,state,url,updatedAt,createdAt,author,labels]` 通过 GitHub REST 列出 issue，默认 `state=open`、`limit=30`，输出稳定 JSON 且不依赖系统 `gh` binary。`--limit` 会映射到 GitHub `per_page` 并限制返回数量，避免一次拉爆上下文；未知 state 或未知 `--json` 字段必须结构化失败并带 `runnerDisposition=business-failed`。GitHub issues API 可能混入 PR，CLI 会从 `.data.issues` 中过滤 pull request。

docs/reference/code-queue-supervision.md

@@ -208,6 +208,14 @@ Git/PR 交付要求：
 - final response 必须报告 head branch、PR URL、远端 head commit、修改文件、验证命令、merge/close 状态和 SHA 或未 merge 原因。
 ```
 
+GPT-5.5 PR/收口类 prompt 在提交前可先用 host commander 辅助 lint 做非阻塞检查：
+
+```bash
+bun scripts/cli.ts commander prompt-lint --kind gpt55-pr --prompt-file /tmp/code-queue-prompt.md
+```
+
+该检查只服务于指挥官补齐派单边界，不是业务 PR 门禁，也不改变 `codex submit` 默认行为。输出只包含 `ok`、`missingClauses`、`riskLevel`、`suggestedPatchSnippet` 和 prompt shape，不回显完整 prompt；`data.ok=false` 表示建议补齐 PR/自合并/rebase/update 授权、artifact build/publish 授权、host-owned DEV rollout、未显式 `ROLLOUT_OK` 时禁止 runner rollout、以及 PROD/secret/DB/破坏性回滚边界。
+
 Runner preflight 优先使用执行面诊断入口：
 
 ```bash

docs/reference/host-codex-commander.md

@@ -27,10 +27,15 @@ bun scripts/cli.ts commander contract
 bun scripts/cli.ts commander plan --dry-run [--session-id primary]
 bun scripts/cli.ts commander smoke --dry-run [--session-id primary]
 bun scripts/cli.ts commander approval request --action <action> --dry-run [--reason text] [--task-id id]
+bun scripts/cli.ts commander prompt-lint --kind gpt55-pr (--prompt-file <file>|--stdin)
 ```
 
 `plan`、`smoke` 与 `approval request` 必须显式使用 `--dry-run`，缺失时返回 `error=dry-run-required`。
 
+`commander prompt-lint --kind gpt55-pr` 是指挥官派 GPT-5.5 PR/收口类任务前的本地辅助检查。它只读取 `--prompt-file` 或 `--stdin`，返回结构化 JSON 字段 `ok`、`missingClauses`、`riskLevel`、`suggestedPatchSnippet`、`promptShape.textEchoed=false` 和 `policy.advisoryOnly=true`；不会提交 Code Queue task、不会修改 scheduler、不会访问 live service，也不会回显完整 prompt。即使 lint 发现缺失条款，CLI envelope 仍保持成功退出，调用方应把 `data.ok=false` 当作派单前修补建议，而不是业务 PR 门禁或 `codex submit` admission 规则。
+
+`gpt55-pr` 当前检查的硬边界包括：普通 PR 创建/更新、自合并/关闭、rebase/update/冲突处理授权；repo-owned CI/CD、build/publish artifact、DEV image/artifact tag/digest/report 授权；DEV deploy apply、rollout 和 live health verification 默认由 host commander 统一执行；未显式包含 `ROLLOUT_OK` 时 runner 不得竞争 DEV CD lock、deploy apply、rollout 或 live verification；禁止 PROD mutation、密钥读取/打印、数据库手工写入和破坏性回滚。缺失时 `suggestedPatchSnippet` 只给可追加的边界片段，不包含原 prompt。
+
 ## Operator-Run Stdio Loop
 
 当前高鲁棒指挥官循环脚本固定放在 `/root/.unidesk/commander_loop.py`，工作目录使用 `/root/unidesk/`。它通过 `codex app-server --listen stdio://` 直连 Codex app-server JSON-RPC，而不是反复启动普通交互式 CLI；外层必须有持续循环和异常保护，fatal error 后自动重启，避免单次 stdio、网络或 app-server 错误让指挥官长期停止。

scripts/cli.ts

@@ -257,6 +257,10 @@ async function main(): Promise<void> {
 
   if (top === "commander") {
     const result = runCommanderCommand(args.slice(1));
+    if (sub === "prompt-lint") {
+      emitJson(commandName, result, true);
+      return;
+    }
     const ok = (result as { ok?: unknown }).ok !== false;
     emitJson(commandName, result, ok);
     if (!ok) process.exitCode = 1;

scripts/host-codex-commander-prompt-lint-contract-test.ts

@@ -0,0 +1,149 @@
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { lintCommanderPrompt } from "./src/commander-prompt-lint";
+
+type JsonRecord = Record<string, unknown>;
+
+function assertCondition(condition: unknown, message: string, detail: unknown = {}): void {
+  if (!condition) throw new Error(`${message}: ${JSON.stringify(detail)}`);
+}
+
+function asRecord(value: unknown, label: string): JsonRecord {
+  assertCondition(typeof value === "object" && value !== null && !Array.isArray(value), `${label} must be an object`, value);
+  return value as JsonRecord;
+}
+
+function asStringArray(value: unknown, label: string): string[] {
+  assertCondition(Array.isArray(value) && value.every((item) => typeof item === "string"), `${label} must be string array`, value);
+  return value as string[];
+}
+
+function runCli(args: string[], stdin?: string): { status: number | null; stdout: string; stderr: string; envelope: JsonRecord } {
+  const result = spawnSync("bun", ["scripts/cli.ts", ...args], {
+    cwd: process.cwd(),
+    input: stdin,
+    encoding: "utf8",
+    maxBuffer: 4 * 1024 * 1024,
+  });
+  assertCondition(String(result.stdout || "").trim().length > 0, `command produced no stdout: ${args.join(" ")}`, {
+    status: result.status,
+    stderr: String(result.stderr || ""),
+  });
+  return {
+    status: result.status,
+    stdout: String(result.stdout || ""),
+    stderr: String(result.stderr || ""),
+    envelope: asRecord(JSON.parse(String(result.stdout || "")) as unknown, "cli envelope"),
+  };
+}
+
+function dataOf(envelope: JsonRecord): JsonRecord {
+  return asRecord(envelope.data, "data");
+}
+
+const completePrompt = `
+UniDesk#20 #118 / commander prompt boundary lint
+
+You are a D601 Code Queue GPT-5.5 runner. Work in UniDesk only.
+
+PR and Git authorization:
+- You may create and update a head branch and PR, rebase/update from origin/master, resolve conflicts, and self-merge/close the ordinary PR when checks pass and the task boundary is satisfied.
+
+Artifact authorization:
+- You may use repo-owned CI/CD, publish, or equivalent controlled build paths to build/publish DEV images or artifacts, and must report commit, image tag, digest, artifact report, and validation evidence.
+
+Rollout boundary:
+- DEV deploy apply, rollout, and live health verification are owned by the host commander unless this prompt explicitly contains ROLLOUT_OK.
+- Without explicit ROLLOUT_OK, do not acquire the DEV CD lock, run deploy apply, run rollout restart, or compete with host commander live verification.
+
+Forbidden:
+- No PROD mutation, no reading or printing secrets/tokens/credentials, no manual database/DB writes, and no destructive rollback.
+`;
+
+const incompletePromptWithSecret = `
+UniDesk#20 #118
+Task: implement the lint. token=ghp_prompt_lint_contract_secret
+Please make code changes and tests.
+`;
+
+const lint = lintCommanderPrompt(completePrompt);
+assertCondition(lint.ok === true, "complete GPT-5.5 PR prompt should pass lint", lint);
+assertCondition(lint.missingClauses.length === 0, "complete prompt should have no missing clauses", lint);
+assertCondition(lint.suggestedPatchSnippet === "", "passing prompt should not include patch snippet", lint);
+assertCondition(lint.policy.advisoryOnly === true, "lint must be advisory only", lint);
+assertCondition(lint.policy.changesCodexSubmitDefault === false, "lint must not change codex submit default", lint);
+assertCondition(JSON.stringify(lint).includes("promptShape"), "lint should expose prompt shape metadata", lint);
+assertCondition(!JSON.stringify(lint).includes("self-merge/close the ordinary PR"), "direct lint result must not echo full prompt", lint);
+
+const failingLint = lintCommanderPrompt(incompletePromptWithSecret);
+assertCondition(failingLint.ok === false, "incomplete prompt should fail lint", failingLint);
+assertCondition(failingLint.riskLevel === "high", "incomplete prompt should be high risk", failingLint);
+for (const expected of [
+  "pr-self-merge-rebase-authorization",
+  "artifact-build-publish-authorization",
+  "host-owned-dev-rollout",
+  "runner-rollout-forbidden-without-rollout-ok",
+  "prod-secret-db-rollback-boundary",
+]) {
+  assertCondition(failingLint.missingClauses.includes(expected), `missing expected clause id ${expected}`, failingLint);
+}
+assertCondition(failingLint.suggestedPatchSnippet.includes("ROLLOUT_OK"), "snippet should mention ROLLOUT_OK", failingLint);
+assertCondition(!JSON.stringify(failingLint).includes("ghp_prompt_lint_contract_secret"), "lint output must not echo secret-like prompt text", failingLint);
+
+const tmp = mkdtempSync(join(tmpdir(), "host-codex-commander-prompt-lint-"));
+try {
+  const promptFile = join(tmp, "prompt.md");
+  writeFileSync(promptFile, incompletePromptWithSecret, "utf8");
+  const fileRun = runCli(["commander", "prompt-lint", "--kind", "gpt55-pr", "--prompt-file", promptFile]);
+  assertCondition(fileRun.status === 0, "commander prompt-lint is advisory and should exit 0 even when lint ok=false", fileRun);
+  assertCondition(fileRun.envelope.ok === true, "CLI envelope should remain ok for advisory lint result", fileRun.envelope);
+  const fileData = dataOf(fileRun.envelope);
+  assertCondition(fileData.ok === false, "lint data ok should reflect missing clauses", fileData);
+  assertCondition(asStringArray(fileData.missingClauses, "missingClauses").includes("host-owned-dev-rollout"), "file lint should report rollout clause", fileData);
+  assertCondition(String(fileData.suggestedPatchSnippet || "").includes("DEV deploy apply"), "file lint should include bounded patch snippet", fileData);
+  assertCondition(!fileRun.stdout.includes("ghp_prompt_lint_contract_secret"), "file lint stdout must not echo prompt secret", fileRun.stdout);
+
+  const stdinRun = runCli(["commander", "prompt-lint", "--kind", "gpt55-pr", "--stdin"], completePrompt);
+  assertCondition(stdinRun.status === 0 && stdinRun.envelope.ok === true, "stdin lint should exit successfully", stdinRun.envelope);
+  const stdinData = dataOf(stdinRun.envelope);
+  assertCondition(stdinData.ok === true, "stdin lint data should pass for complete prompt", stdinData);
+  assertCondition(asStringArray(stdinData.missingClauses, "missingClauses").length === 0, "stdin lint should have no missing clauses", stdinData);
+  assertCondition(!stdinRun.stdout.includes("Artifact authorization:"), "stdin lint must not echo full prompt", stdinRun.stdout);
+} finally {
+  rmSync(tmp, { recursive: true, force: true });
+}
+
+const submitDryRun = runCli(["codex", "submit", "--prompt-stdin", "--queue", "prompt-lint-contract", "--dry-run"], incompletePromptWithSecret);
+assertCondition(submitDryRun.status === 0 && submitDryRun.envelope.ok === true, "codex submit --dry-run should not be gated by commander prompt-lint", submitDryRun.envelope);
+const submitData = dataOf(submitDryRun.envelope);
+assertCondition(asRecord(submitData.request, "submit request").prompt !== undefined, "submit dry-run should keep its existing prompt review behavior", submitData);
+
+const helpRun = runCli(["commander", "--help"]);
+assertCondition(helpRun.status === 0 && helpRun.envelope.ok === true, "commander help should succeed", helpRun.envelope);
+const helpData = dataOf(helpRun.envelope);
+assertCondition(asStringArray(helpData.usage, "help usage").some((line) => line.includes("commander prompt-lint")), "commander help should list prompt-lint", helpData);
+assertCondition(asRecord(helpData.promptLint, "promptLint").gate === "advisory-only; not a business PR gate and not a Code Queue submit admission change", "help should document advisory-only gate", helpData);
+
+const doc = readFileSync("docs/reference/host-codex-commander.md", "utf8");
+for (const snippet of [
+  "commander prompt-lint --kind gpt55-pr",
+  "missingClauses",
+  "suggestedPatchSnippet",
+  "不是业务 PR 门禁",
+]) {
+  assertCondition(doc.includes(snippet), `reference doc missing snippet: ${snippet}`);
+}
+
+process.stdout.write(`${JSON.stringify({
+  ok: true,
+  checks: [
+    "complete GPT-5.5 PR prompt passes commander prompt-lint",
+    "missing PR/artifact/DEV rollout/ROLLOUT_OK/PROD-secret-DB-rollback clauses are reported as high risk",
+    "prompt-lint supports --prompt-file and --stdin",
+    "prompt-lint output does not echo full prompt or secret-like prompt text",
+    "commander prompt-lint remains advisory and does not gate codex submit --dry-run",
+    "commander help and host commander reference document the advisory lint entry",
+  ],
+}, null, 2)}\n`);

scripts/src/check.ts

@@ -28,11 +28,13 @@ const syntaxFiles = [
   "scripts/src/e2e.ts",
   "scripts/src/help.ts",
   "scripts/src/commander.ts",
+  "scripts/src/commander-prompt-lint.ts",
   "scripts/src/recovery-guardrails.ts",
   "scripts/src/server-cleanup.ts",
   "scripts/src/remote.ts",
   "scripts/host-codex-commander-contract-test.ts",
   "scripts/host-codex-commander-no-daemon-smoke-contract-test.ts",
+  "scripts/host-codex-commander-prompt-lint-contract-test.ts",
   "scripts/host-codex-commander-skeleton-contract-test.ts",
   "scripts/auth-broker-contract-test.ts",
   "scripts/code-queue-cli-disclosure-contract-test.ts",
@@ -335,6 +337,7 @@ export function runChecks(config: UniDeskConfig, options: CheckOptions = default
       fileItem("src/components/microservices/host-codex-commander/src/redaction.ts"),
       fileItem("src/components/microservices/host-codex-commander/src/state.ts"),
       fileItem("src/components/microservices/code-queue-mgr/src/prompt-observation.ts"),
+      fileItem("scripts/src/commander-prompt-lint.ts"),
       fileItem("scripts/src/deploy.ts"),
       fileItem("scripts/code-queue-issue3-regression-test.ts"),
       fileItem("scripts/code-queue-liveness-diagnostics-test.ts"),
@@ -355,6 +358,7 @@ export function runChecks(config: UniDeskConfig, options: CheckOptions = default
       fileItem("scripts/code-queue-commander-view-contract-test.ts"),
       fileItem("scripts/host-codex-commander-skeleton-contract-test.ts"),
       fileItem("scripts/host-codex-commander-no-daemon-smoke-contract-test.ts"),
+      fileItem("scripts/host-codex-commander-prompt-lint-contract-test.ts"),
       fileItem("scripts/provider-runner-triage-contract-test.ts"),
       fileItem("scripts/ssh-argv-guidance-contract-test.ts"),
       fileItem("scripts/src/provider-triage.ts"),
@@ -408,6 +412,7 @@ export function runChecks(config: UniDeskConfig, options: CheckOptions = default
     items.push(commandItem("code-queue:commander-view-contract", ["bun", "scripts/code-queue-commander-view-contract-test.ts"], 30_000));
     items.push(commandItem("host-codex-commander:skeleton-contract", ["bun", "scripts/host-codex-commander-skeleton-contract-test.ts"], 30_000));
     items.push(commandItem("host-codex-commander:no-daemon-smoke-contract", ["bun", "scripts/host-codex-commander-no-daemon-smoke-contract-test.ts"], 30_000));
+    items.push(commandItem("host-codex-commander:prompt-lint-contract", ["bun", "scripts/host-codex-commander-prompt-lint-contract-test.ts"], 30_000));
     items.push(commandItem("provider:runner-triage-contract", ["bun", "scripts/provider-runner-triage-contract-test.ts"], 30_000));
     items.push(commandItem("ssh:argv-guidance-contract", ["bun", "scripts/ssh-argv-guidance-contract-test.ts"], 30_000));
     items.push(commandItem("deploy:artifact-matrix-contract", ["bun", "scripts/deploy-artifact-matrix-contract-test.ts"], 90_000));
@@ -449,6 +454,7 @@ export function runChecks(config: UniDeskConfig, options: CheckOptions = default
     items.push(skippedItem("code-queue:commander-view-contract", "Code Queue commander view contract is opt-in with script checks", "--scripts-typecheck or --full"));
     items.push(skippedItem("host-codex-commander:skeleton-contract", "host Codex commander skeleton contract is opt-in with script checks", "--scripts-typecheck or --full"));
     items.push(skippedItem("host-codex-commander:no-daemon-smoke-contract", "host Codex commander no-daemon smoke contract is opt-in with script checks", "--scripts-typecheck or --full"));
+    items.push(skippedItem("host-codex-commander:prompt-lint-contract", "host Codex commander prompt boundary lint contract is opt-in with script checks", "--scripts-typecheck or --full"));
     items.push(skippedItem("provider:runner-triage-contract", "Provider runner triage contract is opt-in with script checks", "--scripts-typecheck or --full"));
     items.push(skippedItem("ssh:argv-guidance-contract", "SSH argv guidance and failure hint contract is opt-in with script checks", "--scripts-typecheck or --full"));
     items.push(skippedItem("deploy:artifact-matrix-contract", "deploy artifact matrix contract is opt-in with script checks", "--scripts-typecheck or --full"));

scripts/src/commander-prompt-lint.ts

@@ -0,0 +1,245 @@
+import { readFileSync } from "node:fs";
+
+export type CommanderPromptLintKind = "gpt55-pr";
+export type CommanderPromptLintRiskLevel = "low" | "medium" | "high";
+
+interface ClauseCheck {
+  id: string;
+  label: string;
+  required: boolean;
+  matched: boolean;
+  severity: "medium" | "high";
+  suggestion: string;
+}
+
+export interface CommanderPromptLintResult {
+  ok: boolean;
+  kind: CommanderPromptLintKind;
+  missingClauses: string[];
+  riskLevel: CommanderPromptLintRiskLevel;
+  suggestedPatchSnippet: string;
+  promptShape: {
+    chars: number;
+    lines: number;
+    textEchoed: false;
+  };
+  policy: {
+    advisoryOnly: true;
+    mutatesScheduler: false;
+    changesCodexSubmitDefault: false;
+    printsPromptText: false;
+    supportedInputs: Array<"--stdin" | "--prompt-file">;
+    reference: string;
+  };
+}
+
+interface ParsedPromptLintArgs {
+  kind: CommanderPromptLintKind;
+  prompt: string;
+}
+
+const gpt55PrSnippet = [
+  "GPT-5.5 runner boundary:",
+  "- You may create/update the branch and PR, resolve conflicts, rebase/update from the target branch, and self-merge/close an ordinary PR when checks pass and the task boundary is satisfied.",
+  "- You may use repo-owned CI/CD, publish, or equivalent controlled build paths to build/publish DEV images or artifacts, and must report commit, image tag, digest, artifact report, and validation evidence.",
+  "- DEV deploy apply, rollout, and live health verification are owned by the host commander unless this prompt explicitly contains ROLLOUT_OK.",
+  "- Without explicit ROLLOUT_OK, do not acquire the DEV CD lock, run deploy apply, perform rollout/restart, or compete with host commander live verification.",
+  "- Forbidden: PROD mutation, reading or printing secrets, manual database writes, destructive rollback, Code Queue backend/scheduler restart, or interrupt/cancel running tasks unless explicitly authorized.",
+].join("\n");
+
+function hasFlag(args: string[], flag: string): boolean {
+  return args.includes(flag);
+}
+
+function optionValue(args: string[], names: string[]): string | undefined {
+  for (const name of names) {
+    const index = args.indexOf(name);
+    if (index === -1) continue;
+    const value = args[index + 1];
+    if (value === undefined || value.startsWith("--")) throw new Error(`${name} requires a value`);
+    return value;
+  }
+  return undefined;
+}
+
+function assertKnownOptions(args: string[]): void {
+  const flags = new Set(["--stdin"]);
+  const valueOptions = new Set(["--kind", "--prompt-file", "--file"]);
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index] ?? "";
+    if (!arg.startsWith("--")) throw new Error(`commander prompt-lint does not accept positional prompt text; use --stdin or --prompt-file`);
+    if (flags.has(arg)) continue;
+    if (valueOptions.has(arg)) {
+      index += 1;
+      if (index >= args.length) throw new Error(`${arg} requires a value`);
+      continue;
+    }
+    throw new Error(`unknown commander prompt-lint option: ${arg}`);
+  }
+}
+
+function parseKind(raw: string | undefined): CommanderPromptLintKind {
+  const kind = raw ?? "gpt55-pr";
+  if (kind !== "gpt55-pr") throw new Error(`unsupported commander prompt-lint kind: ${kind}`);
+  return kind;
+}
+
+function readPromptFromArgs(args: string[]): string {
+  const promptFile = optionValue(args, ["--prompt-file", "--file"]);
+  const promptStdin = hasFlag(args, "--stdin");
+  const sources = [promptFile !== undefined, promptStdin].filter(Boolean).length;
+  if (sources !== 1) throw new Error("commander prompt-lint requires exactly one prompt source: --prompt-file or --stdin");
+  const prompt = promptFile !== undefined
+    ? (promptFile === "-" ? readFileSync(0, "utf8") : readFileSync(promptFile, "utf8"))
+    : readFileSync(0, "utf8");
+  if (prompt.trim().length === 0) throw new Error("commander prompt-lint prompt must not be empty");
+  return prompt;
+}
+
+export function parseCommanderPromptLintArgs(args: string[]): ParsedPromptLintArgs {
+  assertKnownOptions(args);
+  return {
+    kind: parseKind(optionValue(args, ["--kind"])),
+    prompt: readPromptFromArgs(args),
+  };
+}
+
+function any(patterns: RegExp[], prompt: string): boolean {
+  return patterns.some((pattern) => pattern.test(prompt));
+}
+
+function rolloutOkPresent(prompt: string): boolean {
+  return /\bROLLOUT_OK\b/u.test(prompt);
+}
+
+function gpt55PrClauseChecks(prompt: string): ClauseCheck[] {
+  const prAuthorization = any([
+    /\bPR\b[^\n。]{0,120}(?:create|update|push|branch|merge|close|rebase|conflict)/iu,
+    /(?:创建|更新|push|提交|合并|关闭|rebase|解决冲突)[^\n。]{0,80}\bPR\b/iu,
+  ], prompt) && any([
+    /self[- ]?(?:merge|close)|自行(?:合并|关闭|收口)|自合并|自收口/iu,
+    /merge\/close|合并\/关闭/iu,
+  ], prompt) && any([
+    /\brebase\b|\bupdate\b|解决冲突|更新(?:目标|base|master|分支)/iu,
+  ], prompt);
+
+  const artifactAuthorization = any([
+    /\b(?:build|publish)\b[^\n。]{0,80}\b(?:artifact|image|DEV image|镜像|制品)\b/iu,
+    /\b(?:artifact|image|镜像|制品)\b[^\n。]{0,80}\b(?:build|publish|tag|digest|构建|发布)\b/iu,
+    /(?:构建|发布)[^\n。]{0,80}(?:镜像|制品|artifact|image)/iu,
+  ], prompt) && any([
+    /\b(?:tag|digest|artifact report|image tag)\b/iu,
+    /(?:镜像\s*tag|digest|制品报告|artifact report)/iu,
+  ], prompt);
+
+  const hostOwnsDevRollout = any([
+    /DEV[^\n。]{0,120}(?:deploy apply|rollout|live health|live verification)[^\n。]{0,120}(?:host commander|commander|host|统一执行|统一处理|统一复验)/iu,
+    /(?:host commander|commander|host|指挥官)[^\n。]{0,120}DEV[^\n。]{0,120}(?:deploy apply|rollout|live health|live verification|发布|上线|复验)/iu,
+    /DEV[^\n。]{0,80}(?:发布|上线|rollout|复验)[^\n。]{0,80}(?:host|commander|指挥官|统一)/iu,
+  ], prompt);
+
+  const forbidsRunnerRolloutUnlessOk = any([
+    /unless[^\n。]{0,80}\bROLLOUT_OK\b/iu,
+    /未显式[^\n。]{0,60}\bROLLOUT_OK\b[^\n。]{0,80}(?:不要|不得|禁止|do not|don't|must not)/iu,
+    /\bROLLOUT_OK\b[^\n。]{0,80}(?:才|unless|only if|explicit)/iu,
+  ], prompt) && any([
+    /(?:do not|don't|must not|禁止|不要|不得)[^\n。]{0,100}(?:DEV CD lock|deploy apply|rollout|live health|rollout restart|竞争|抢)/iu,
+    /(?:DEV CD lock|deploy apply|rollout|live health|rollout restart|竞争|抢)[^\n。]{0,100}(?:do not|don't|must not|禁止|不要|不得)/iu,
+  ], prompt);
+
+  const prodForbidden = any([
+    /(?:禁止|不要|不得|must not|do not|don't|\bno\b|forbid|forbidden)[^\n。]{0,80}(?:PROD|prod|production|生产)/iu,
+    /(?:PROD|prod|production|生产)[^\n。]{0,80}(?:禁止|不要|不得|must not|do not|don't|\bno\b|forbid|forbidden|not allowed)/iu,
+  ], prompt);
+  const secretForbidden = any([
+    /(?:禁止|不要|不得|must not|do not|don't|\bno\b|forbid|forbidden)[^\n。]{0,80}(?:secret|token|credential|密钥|凭证)/iu,
+    /(?:secret|token|credential|密钥|凭证)[^\n。]{0,80}(?:禁止|不要|不得|must not|do not|don't|\bno\b|forbid|forbidden|not allowed|读取|打印)/iu,
+  ], prompt);
+  const dbForbidden = any([
+    /(?:禁止|不要|不得|must not|do not|don't|\bno\b|forbid|forbidden)[^\n。]{0,80}(?:database|DB|数据库)/iu,
+    /(?:database|DB|数据库)[^\n。]{0,80}(?:manual|手工|patch|write|写入|禁止|不要|不得|must not|do not|don't|\bno\b)/iu,
+  ], prompt);
+  const rollbackForbidden = any([
+    /(?:禁止|不要|不得|must not|do not|don't|\bno\b|forbid|forbidden)[^\n。]{0,80}(?:destructive rollback|破坏性回滚|回滚)/iu,
+    /(?:destructive rollback|破坏性回滚)[^\n。]{0,80}(?:禁止|不要|不得|must not|do not|don't|\bno\b|forbid|forbidden|not allowed)/iu,
+  ], prompt);
+
+  return [
+    {
+      id: "pr-self-merge-rebase-authorization",
+      label: "PR/自合并/rebase/update 授权文本",
+      required: true,
+      matched: prAuthorization,
+      severity: "high",
+      suggestion: "明确授权 runner 创建/更新 PR、rebase/update/解决冲突，并在普通 PR 满足任务边界和检查通过时自合并/关闭。",
+    },
+    {
+      id: "artifact-build-publish-authorization",
+      label: "build/publish artifact 授权文本",
+      required: true,
+      matched: artifactAuthorization,
+      severity: "high",
+      suggestion: "明确授权使用 repo-owned CI/CD 或受控构建路径发布 DEV image/artifact，并要求回报 tag、digest 和 artifact report。",
+    },
+    {
+      id: "host-owned-dev-rollout",
+      label: "DEV deploy apply/rollout/live verification 由 host 统一执行文本",
+      required: true,
+      matched: hostOwnsDevRollout,
+      severity: "high",
+      suggestion: "写明 DEV deploy apply、rollout 和 live health verification 默认由 host commander 统一执行。",
+    },
+    {
+      id: "runner-rollout-forbidden-without-rollout-ok",
+      label: "未显式 ROLLOUT_OK 时禁止 runner rollout",
+      required: true,
+      matched: forbidsRunnerRolloutUnlessOk,
+      severity: "high",
+      suggestion: "写明未显式包含 ROLLOUT_OK 时，runner 不得抢 DEV CD lock、deploy apply、rollout 或 live verification。",
+    },
+    {
+      id: "prod-secret-db-rollback-boundary",
+      label: "PROD/secret/DB/破坏性回滚边界",
+      required: true,
+      matched: prodForbidden && secretForbidden && dbForbidden && rollbackForbidden,
+      severity: "high",
+      suggestion: "同时禁止 PROD mutation、密钥读取/打印、数据库手工写入和破坏性回滚。",
+    },
+  ];
+}
+
+export function lintCommanderPrompt(prompt: string, kind: CommanderPromptLintKind = "gpt55-pr"): CommanderPromptLintResult {
+  const clauses = gpt55PrClauseChecks(prompt);
+  const missingClauses = clauses.filter((clause) => clause.required && !clause.matched).map((clause) => clause.id);
+  const highMissing = clauses.some((clause) => clause.severity === "high" && !clause.matched);
+  const rolloutOk = rolloutOkPresent(prompt);
+  const riskLevel: CommanderPromptLintRiskLevel = missingClauses.length === 0
+    ? rolloutOk ? "medium" : "low"
+    : highMissing ? "high" : "medium";
+
+  return {
+    ok: missingClauses.length === 0,
+    kind,
+    missingClauses,
+    riskLevel,
+    suggestedPatchSnippet: missingClauses.length === 0 ? "" : gpt55PrSnippet,
+    promptShape: {
+      chars: prompt.length,
+      lines: prompt.split(/\r\n|\r|\n/u).length,
+      textEchoed: false,
+    },
+    policy: {
+      advisoryOnly: true,
+      mutatesScheduler: false,
+      changesCodexSubmitDefault: false,
+      printsPromptText: false,
+      supportedInputs: ["--stdin", "--prompt-file"],
+      reference: "docs/reference/host-codex-commander.md",
+    },
+  };
+}
+
+export function runCommanderPromptLintCommand(args: string[]): CommanderPromptLintResult {
+  const options = parseCommanderPromptLintArgs(args);
+  return lintCommanderPrompt(options.prompt, options.kind);
+}

scripts/src/commander.ts

@@ -1,6 +1,7 @@
 import { buildCommanderApprovalNotificationDraft, commanderApprovalNotificationPathUnavailable } from "../../src/components/microservices/host-codex-commander/src/approval-notification";
 import { commanderContract as hostCommanderContract, commanderHighRiskActions as highRiskActions } from "../../src/components/microservices/host-codex-commander/src/contract";
 import { redactText } from "../../src/components/microservices/host-codex-commander/src/redaction";
+import { runCommanderPromptLintCommand } from "./commander-prompt-lint";
 
 const requiredDryRunMessage = "This host Codex commander skeleton only supports dry-run planning; live daemon/control operations are not implemented.";
 
@@ -36,6 +37,7 @@ function commanderHelp(): Record<string, unknown> {
       "bun scripts/cli.ts commander plan --dry-run [--session-id id]",
       "bun scripts/cli.ts commander smoke --dry-run [--session-id id]",
       "bun scripts/cli.ts commander approval request --action <action> --dry-run [--reason text] [--task-id id]",
+      "bun scripts/cli.ts commander prompt-lint --kind gpt55-pr (--prompt-file <file>|--stdin)",
     ],
     highRiskActions,
     reference: "docs/reference/host-codex-commander.md",
@@ -494,6 +496,7 @@ export function runCommanderCommand(args: string[]): Record<string, unknown> {
   if (sub === "plan") return commanderPlan(args.slice(1));
   if (sub === "smoke") return commanderSmoke(args.slice(1));
   if (sub === "approval" && second === "request") return commanderApprovalRequest(args.slice(2));
+  if (sub === "prompt-lint") return runCommanderPromptLintCommand(args.slice(1)) as unknown as Record<string, unknown>;
   return {
     ok: false,
     error: "unsupported-command",

scripts/src/help.ts

@@ -47,7 +47,7 @@ export function rootHelp(): unknown {
       { command: "artifact-registry plan|render|status|health|install|deploy-backend-core|deploy-service", description: "Manage the D601 host-managed CNCF Distribution registry and run pull-only artifact CD for supported services, including D601 direct, k3s-managed, and code-queue dev-only consumers." },
       { command: "auth-broker contract|health --dry-run|credential-request --dry-run|pr-preflight --dry-run", description: "Inspect the P0 Rust auth broker and CLI adapter contract without reading token values, writing GitHub, or starting services." },
       { command: "gh preflight|auth|issue|pr", description: "Run safe GitHub issue and PR CRUD/lifecycle operations through REST with body-file update replace/append, comment delete, token diagnostics, PR closeout preflight, hard delete unsupported, and merge blocked." },
-      { command: "commander contract|plan --dry-run|smoke --dry-run|approval request --dry-run", description: "Host Codex commander skeleton contract, no-daemon smoke plan, and dry-run approval preview; generates <=200 char Chinese ClaudeQQ drafts plus backend-core proxy command without live bridges or message sends." },
+      { command: "commander contract|plan --dry-run|smoke --dry-run|approval request --dry-run|prompt-lint --kind gpt55-pr", description: "Host Codex commander skeleton contract, no-daemon smoke plan, dry-run approval preview, and advisory GPT-5.5 PR prompt boundary lint without live bridges, message sends, or submit gating." },
       { command: "code-agent-sandbox", description: "Independent Code Agent Sandbox service skeleton for adapter, mode, and credential-boundary diagnostics." },
       { command: "schedule list|get|runs|run|retry-run|delete", description: "Manage backend-core scheduled tasks and run history; schedule run <id> supports --wait-ms N and retry-run reuses the failed run's schedule." },
       { command: "schedule upsert-pgdata-backup [--time HH:MM] [--remote-base /SERVER_DATA/UNIDESK_PG_DATA]", description: "Create or update the daily PGDATA physical backup task that uploads monthly rotated archives to Baidu Netdisk." },
@@ -213,22 +213,31 @@ function providerHelp(): unknown {
 
 function commanderHelp(): unknown {
   return {
-    command: "commander contract|plan|smoke|approval",
+    command: "commander contract|plan|smoke|approval|prompt-lint",
     output: "json",
     usage: [
       "bun scripts/cli.ts commander contract",
       "bun scripts/cli.ts commander plan --dry-run [--session-id id]",
       "bun scripts/cli.ts commander smoke --dry-run [--session-id id]",
       "bun scripts/cli.ts commander approval request --action <action> --dry-run [--reason text] [--task-id id]",
+      "bun scripts/cli.ts commander prompt-lint --kind gpt55-pr (--prompt-file <file>|--stdin)",
     ],
-    description: "Inspect the local host Codex commander skeleton contract, dry-run planner, no-daemon smoke validation plan, state helpers, trace summary aggregator, and approval draft preview with a backend-core ClaudeQQ proxy command.",
+    description: "Inspect the local host Codex commander skeleton contract, dry-run planner, no-daemon smoke validation plan, state helpers, trace summary aggregator, approval draft preview, and advisory GPT-5.5 PR prompt boundary lint.",
     boundary: [
       "the current skeleton is local-only and never attaches to live bridges",
       "dry-run commands never open SSH, PTY, or stdio bridges",
       "high-risk actions only produce a <=200 char Chinese ClaudeQQ approval draft and notification-path-unavailable blocker",
       "authorized future sends must use backend-core /api/microservices/claudeqq/proxy, not local skill or powershell paths",
+      "prompt-lint is commander advisory output and does not change codex submit default behavior",
       "token and secret values must never be printed",
     ],
+    promptLint: {
+      command: "bun scripts/cli.ts commander prompt-lint --kind gpt55-pr --prompt-file <path>",
+      stdin: "cat prompt.md | bun scripts/cli.ts commander prompt-lint --kind gpt55-pr --stdin",
+      outputFields: ["ok", "missingClauses", "riskLevel", "suggestedPatchSnippet"],
+      fullPromptEchoed: false,
+      gate: "advisory-only; not a business PR gate and not a Code Queue submit admission change",
+    },
     reference: "docs/reference/host-codex-commander.md",
   };
 }