docs: 固化 L1 CLI 即时修复规则

docs/reference/dev-environment.md

@@ -80,9 +80,50 @@ trans D601:/home/ubuntu/workspace/unidesk-dev git remote -v
   - 该例外使用 `CARGO_BUILD_JOBS=1`、`--jobs 1` 或 CLI 内置等价方式限制并发；
   - 结果必须用异步 job/status/health 证据回写 issue。
 
-`scripts/cli.ts`、`scripts/trans`、`scripts/tran`、`scripts/src/ssh.ts` 和相邻的 `trans`/`tran`/SSH helper 是主 server 上人工与 Codex 高频使用的控制入口；这类客户端工具链改进可以直接在 master server `/root/unidesk` 轻量修改、提交并推送到 `origin/master`。该例外只覆盖 CLI/trans/tran 客户端源码、帮助、语法/命令形态验证和对应 reference 文档，不覆盖 `src/components/provider-gateway` 行为变更、镜像构建、仓库级 check、浏览器 smoke 或其他重型验证。除非用户明确要求，CLI 改动不做单元测试、合同测试或新增测试脚本。涉及 provider-gateway 代码时仍必须遵循 provider-gateway 版本和远程升级规则。
+- 主 server 高频控制入口包括：
+  - `scripts/cli.ts`；
+  - `scripts/trans`；
+  - `scripts/tran`；
+  - `scripts/src/ssh.ts`；
+  - 相邻的 `trans`、`tran` 和 SSH helper。
+- 这些客户端工具链可以直接在 master server `/root/unidesk` 轻量修改、提交并推送到 `origin/master`：
+  - 例外范围只覆盖 CLI、`trans`、`tran` 客户端源码；
+  - 同时覆盖帮助、轻量语法或命令形态验证和对应 reference 文档；
+  - 不覆盖 `src/components/provider-gateway` 行为变更；
+  - 不覆盖镜像构建、仓库级 check、浏览器 smoke 或其他重型验证；
+  - 除非用户明确要求，CLI 改动不做单元测试、合同测试或新增测试脚本；
+  - 涉及 provider-gateway 代码时，继续遵循其版本和远程升级规则。
+- `trans`、`tran` 或 SSH 透传出现以下高频摩擦时，先优化 CLI 客户端：
+  - 文件传输、stdin、chunk 或编码；
+  - timeout；
+  - route 或 operation 解析。
+- 客户端优化应覆盖分块、校验、重试、可观测输出和帮助文档：
+  - 使用目标 provider、pod 或 Windows route 的最小闭环证明；
+  - 只有证据显示 client 侧无法规避边界时，才进入 provider-gateway 变更流程。
 
-当 `trans`/`tran`/SSH 透传的文件传输、stdin、chunk、编码、timeout 或 route/operation 解析出现高频摩擦时，先优化 CLI 客户端的分块、校验、重试、可观测输出和帮助文档，并用目标 provider/pod/Windows route 的最小闭环证明；只有证据显示 client 侧无法规避 provider-gateway 边界时，才进入 provider-gateway 变更流程。
+## L1 受控 CLI 即时修复
+
+- 执行 L1 开发、诊断或验收时，发现项目受控 CLI 存在问题即可在当前任务内即时修改：
+  - 不需要把 CLI 缺陷降级为只读 blocker；
+  - 不需要等待独立任务、issue 或额外授权；
+  - 修复后继续完成原 L1 主线，不因 CLI 自身问题改用裸脚本或绕过产品入口。
+- 可即时修改的范围包括：
+  - YAML parser、参数校验和受控 lifecycle；
+  - `--over-api` transport、状态、日志和窄查询；
+  - 结构化输出、错误码、进度可见性和帮助文本；
+  - 为恢复原 L1 入口所必需的相邻轻量 helper。
+- 即时修改仍遵守原有边界：
+  - owning YAML 继续是运行事实唯一来源；
+  - 不由 CLI 缺陷推导服务端、生产、Secret、安全机制或重型构建的额外修改授权；
+  - 修改使用正常 Git/PR 交付路径，并保护固定 worktree 中的并行改动；
+  - 验证以具体文件语法、配置解析、目标命令和原 L1 入口最小闭环为准；
+  - 默认不新增测试，不在 Master server 运行仓库级检查或重型 smoke。
+- 以下情况属于应即时修复的 CLI 可见性问题：
+  - 输出缺少关键状态、失败阶段或下一步；
+  - 默认输出超过预算，导致无法完成判断。
+  - 修复要求：
+    - 优先补语义化摘要、稳定 identity、分页 cursor 或 id-specific drill-down；
+    - 禁止长期依赖 `--raw`、临时 dump、运行面反解或裸原生工具代替受控 CLI。
 
 ## Public Dev Frontend Port