From 67fee32beb93d48117dca215b364c883dfd6a5af Mon Sep 17 00:00:00 2001 From: Codex Date: Sat, 23 May 2026 02:25:32 +0000 Subject: [PATCH] docs: classify dev smoke mutation authority --- docs/reference/code-queue-supervision.md | 30 ++++++++++++++++++++++++ docs/reference/host-codex-commander.md | 2 ++ 2 files changed, 32 insertions(+) diff --git a/docs/reference/code-queue-supervision.md b/docs/reference/code-queue-supervision.md index 12b0f706..55a5c920 100644 --- a/docs/reference/code-queue-supervision.md +++ b/docs/reference/code-queue-supervision.md @@ -42,6 +42,36 @@ live-read browser audit 只用于观察已部署 UI，不授权写入。未获 每次新派一批任务、接收一批 completed unread 结果，或者发生实质态势变化时，都要同步更新 `#20` 的正文主表；如果当天有滚动简报，则同时更新当日简报 issue 的正文主内容，而不是只在聊天中补上下文。 +## DEV 测试授权分级 + +`DEV` 只说明目标环境，不自动说明允许的写入级别。所有 runner prompt 和 supervisor closeout 都必须把 DEV 验证分成 `read-only`、`live-read` 和 `live-mutating` 三类；如果 prompt 没有显式分类，默认按 `read-only` 处理。 + +| 分级 | 含义 | 常见允许动作 | 禁止动作 | +| --- | --- | --- | --- | +| `read-only` | 不连接或不观察正在运行的 DEV 服务，只验证源码、本地 contract、fixture、mock、dry-run 或静态输出。 | `git diff`、`rg`、类型检查、unit/contract test、CLI `--dry-run`、生成计划或补文档。 | 访问 live service、触发任务、写数据库、部署、重启、rollout、真实硬件或虚拟硬件动作。 | +| `live-read` | 读取正在运行的 DEV 服务、日志、health、status、metrics、Kubernetes 只读对象或只读 API，不改变 live 状态。 | `GET /health`、`GET /status`、只读 proxy、`kubectl get/describe/logs`、只读 CLI status/diagnostics。 | `POST/PUT/PATCH/DELETE`、`kubectl apply/delete/rollout restart`、触发 schedule/job/task、写 issue/PR 之外的 runtime 状态、任何会创建 operation/audit/evidence 的动作。 | +| `live-mutating` | 在 DEV 环境执行会改变 live 状态的命令，即使目标是 smoke、复测或诊断。 | 经 prompt 明确授权的 dev deploy/apply/rollout、trigger/run/retry、task submit/steer、写配置、创建 operation/audit/evidence、HWLAB M3 DO/DI 链路触发。 | 任何未被 prompt 精确列出的 live mutation；生产写入、密钥读取、数据库手工 patch、Code Queue 高风险干预仍按更高安全边界处理。 | + +`DEV smoke`、`M3 smoke`、`live smoke`、`复测`、`验证` 这类词本身不构成 live mutation 授权。只要命令会改变 DEV runtime、触发真实或虚拟设备动作、创建任务/operation/audit/evidence、改变 deployment 或写入服务状态，就必须归入 `live-mutating`。 + +派单 prompt 必须显式写出： + +- `DEV test class`：只能是 `read-only`、`live-read` 或 `live-mutating`。 +- `允许的 live mutation`：若 class 是 `live-mutating`，必须逐项列出允许的命令形态或动作、目标环境/服务/namespace、可接受的状态变化、观察和回滚步骤；若没有授权，写 `none`。 +- `禁止动作`：至少说明 prod mutation、密钥明文、数据库手工 patch、Code Queue backend 重启/重建、运行中任务 interrupt/cancel 是否禁止；未写明的高风险动作一律禁止。 +- `closeout 字段`：runner final response 必须报告实际执行的 test class、是否发生 live mutation、执行命令摘要、目标环境、证据链接或 ID，以及未覆盖风险。 + +runner 收到未分类或含糊的 prompt 时，只能执行 `read-only` 范围；如果完成任务需要 `live-read` 或 `live-mutating`，必须停在计划和待授权状态，列出拟执行命令、风险和需要指挥官补充的授权，不能自行把“DEV”解释成允许写入。 + +supervisor closeout 不能只看 runner 的成功自述，必须核对 prompt 授权和实际命令级别： + +- `read-only` closeout 应证明没有 live service 写入，证据来自 diff、静态检查、unit/contract test 或 dry-run 输出。 +- `live-read` closeout 应记录读取的 DEV endpoint、service、namespace 或日志范围，并明确没有触发 runtime 状态变化。 +- `live-mutating` closeout 应指出 prompt 中的明确授权、实际变更目标、operation/audit/evidence/task/job ID、回滚或恢复观察，以及 prod 未触碰。 +- 如果 runner 在没有明确 prompt 授权时执行了 live mutation，即使 smoke 结果成功，也不能把任务验收为正常完成；指挥官应先核实 live 状态和 blast radius，再把它记录为治理缺陷或 follow-up，并修正后续 prompt 模板。 + +HWLAB M3 口径使用同一分级：只读报告、fixture、LOCAL/DRY-RUN 和 diagnostics 只能算 `read-only` 或 `live-read`；触发 `res_boxsimu_1:DO1 -> hwlab-patch-panel -> res_boxsimu_2:DI1` 的可信闭环属于 `live-mutating`，必须有 prompt 明确授权并在 closeout 中给出 operation / audit / evidence 关联。 + ## 任务设计 每个 Code Queue task 都必须有清晰且狭窄的 ownership 边界。 diff --git a/docs/reference/host-codex-commander.md b/docs/reference/host-codex-commander.md index 20a87685..961a8e44 100644 --- a/docs/reference/host-codex-commander.md +++ b/docs/reference/host-codex-commander.md @@ -67,6 +67,8 @@ host commander 不直接编辑 HWLAB 业务代码，不以本地热修绕过 HWL `commander smoke --dry-run` 是无 daemon smoke contract。它只输出验证计划，不启动 HTTP daemon、不打开 SSH/PTY/stdio bridge、不发送 ClaudeQQ、不重启服务、不 interrupt/cancel 任务、不部署、不跑全量 check/e2e。 +指挥官派发或审阅任何 `DEV smoke` 时，必须沿用 `docs/reference/code-queue-supervision.md` 的 DEV 测试授权分级：未显式授权的 smoke 默认是 `read-only`；读取 live DEV 状态必须标成 `live-read`；触发 deploy、rollout、task、operation、audit、evidence 或硬件/虚拟硬件链路的 smoke 必须标成 `live-mutating`，并在 prompt 中逐项列出授权命令和 closeout 证据要求。 + 需要验证的 source/contract 面： - health endpoint：用 `createCommanderRequestHandler` 和临时 `RuntimeConfig` 调用 `GET /health`，期望返回 `service=host-codex-commander`、`stateRoot` 和日志文件路径；禁止 `Bun.serve` 和端口监听。