Merge remote-tracking branch 'origin/master' into feat/2010-hwlab-release-production-lane

2026-07-15 10:46:53 +02:00
parent 67e5bc0260 7a8fb6635b
commit 29ff108a80
53 changed files with 1791 additions and 44 deletions
@@ -0,0 +1,46 @@
+# AgentRun 开发/生产双环境
+
+范围：AgentRun development（`nc01-v02` / `agentrun-v02`）与 production（`nc01-release` / `agentrun-release`）双 lane 隔离、自动交付与 HWLAB 绑定。namespace 为隔离边界；不为每个子 issue 新建 MDTODO 文件。
+
+主 issue：[UniDesk #2154](https://github.com/pikasTech/unidesk/issues/2154)。
+
+
+## R1 [completed]
+
+R1 建立 agentrun-release namespace 隔离骨架（#2154），完成任务后将详细报告写入[任务报告](./details/agentrun-dev-production-lanes/R1_Task_Report.md)。
+
+### R1.1 [completed]
+
+创建 GitHub 主 issue 与本 MDTODO 登记，完成任务后将详细报告写入[任务报告](./details/agentrun-dev-production-lanes/R1.1_Task_Report.md)。
+### R1.2 [completed]
+
+NC01 k3s 创建 agentrun-release Namespace 与 labels，完成任务后将详细报告写入[任务报告](./details/agentrun-dev-production-lanes/R1.2_Task_Report.md)。
+### R1.3 [completed]
+
+config/agentrun.yaml 声明 nc01-release lane（runtime.namespace=agentrun-release），完成任务后将详细报告写入[任务报告](./details/agentrun-dev-production-lanes/R1.3_Task_Report.md)。
+### R1.4 [completed]
+
+验证 ns Active、lane 可解析、nc01-v02 plan 无回归，完成任务后将详细报告写入[任务报告](./details/agentrun-dev-production-lanes/R1.4_Task_Report.md)。
+## R2
+
+R2 agentrun.yaml 模板参数化，nc01-v02 行为不变，完成任务后将详细报告写入[任务报告](./details/agentrun-dev-production-lanes/R2_Task_Report.md)。
+
+## R3 [completed]
+
+R3 PaC/Gitea/GitOps 生产链 agentrun-nc01-release，完成任务后将详细报告写入[任务报告](./details/agentrun-dev-production-lanes/R3_Task_Report.md)。
+
+## R4 [completed]
+
+R4 DB/Secret/provider 独立物化到 agentrun-release，完成任务后将详细报告写入[任务报告](./details/agentrun-dev-production-lanes/R4_Task_Report.md)。
+
+## R5 [completed]
+
+R5 release 命名空间上线 manager 与内网 canary，完成任务后将详细报告写入[任务报告](./details/agentrun-dev-production-lanes/R5_Task_Report.md)。
+
+## R6
+
+R6 HWLAB 双环境绑定矩阵（dev→v02，prod→release），完成任务后将详细报告写入[任务报告](./details/agentrun-dev-production-lanes/R6_Task_Report.md)。
+
+## R7
+
+R7 文档/CLI help/GC selector 与默认 lane 收敛，完成任务后将详细报告写入[任务报告](./details/agentrun-dev-production-lanes/R7_Task_Report.md)。
@@ -124,6 +124,10 @@
 ### R5.9 [in_progress]

 解决 [AgentRun #356](https://github.com/pikasTech/agentrun/issues/356)：修复 runner Job 已不存在且 lease 过期后，非终态 active turn admission 仍以 `session-turn-admission-active` 阻塞同 session `send`；按既有 SPEC 在 memory/PostgreSQL authority 内原子终结或隔离陈旧 admission 并创建新 run/turn/runner，保留 fresh active steer/并发拒绝，不新增第二 session authority、租约、围栏或客户端 retry，并与 PikaOA MVP 并行且不作为业务门禁，完成任务后将详细报告写入[任务报告](./details/agentrun-runtime-reliability/R5.9_Task_Report.md)。
+### R5.10 [completed]
+
+解决 [AgentRun #363](https://github.com/pikasTech/agentrun/issues/363)：旧 PipelineRun 在新 revision 已发布后才解除 admission 排队并把 `nc01-v0.2-gitops` 回退到旧 sourceCommit，导致 Artificer 重新加载已删除的 `sub2api` AipodSpec；PaC promote 必须以 source branch 最新 revision 为 authority，把过期运行处理为 `warning=true`、`blocking=false`、成功 no-op，禁止覆盖更新 GitOps，并通过自动 PaC 恢复 pika/grok AipodSpec。禁止人工 PipelineRun、Argo sync、数据库修改、第二 authority或 fallback；调试 patch 只允许按 `$unidesk-daddev` P2 最小可逆执行，终态必须由 owning YAML/源码和自动 CI/CD 收敛，完成任务后将详细报告写入[任务报告](./details/agentrun-runtime-reliability/R5.10_Task_Report.md)。
+
 ## R6 [completed]

 将“先恢复运行面再工程化”固化为 unidesk-subagent 的泛化主线规则：运行面恢复关键路径由主代理控制，低耦合工程化任务及时并行，恢复后继续完成工程化交付；将单 PR 收口、复用 guarded merge 内建 preflight、避免仅补 merge SHA 的重复 PR 和减少碎片化 GitHub 查询固化到 unidesk-gh 及相关 reference，并让 merge 默认摘要直接披露 merge commit 与 mergedAt，完成任务后将详细报告写入[任务报告](./details/agentrun-runtime-reliability/R6_Task_Report.md)。
@@ -0,0 +1,10 @@
+# R1.1 任务报告
+
+## 结论
+
+已创建主 issue 与 MDTODO 域文件。
+
+## 证据
+
+- Issue: https://github.com/pikasTech/unidesk/issues/2154
+- MDTODO: `docs/MDTODO/agentrun-dev-production-lanes.md`
@@ -0,0 +1,11 @@
+# R1.2 任务报告
+
+## 结论
+
+NC01 k3s 已创建 `agentrun-release` Namespace，status=Active。
+
+## 证据
+
+- labels: `app.kubernetes.io/part-of=agentrun`, `agentrun.pikastech.local/lane=release`, `agentrun.pikastech.local/role=production`, `agentrun.pikastech.local/node=NC01`
+- annotations: `unidesk.ai/lane-id=nc01-release`, owner issue #2154
+- 命令: `trans NC01:k3s kubectl get ns agentrun-release`
@@ -0,0 +1,21 @@
+# R1.3 任务报告
+
+## 结论
+
+`config/agentrun.yaml` 已声明 `controlPlane.lanes.nc01-release`，runtime.namespace=`agentrun-release`。
+
+## 隔离字段
+
+| 字段 | nc01-v02 | nc01-release |
+|------|----------|--------------|
+| namespace | agentrun-v02 | agentrun-release |
+| source.branch | v0.2 | release |
+| workspace | /root/agentrun-v02 | /root/agentrun-release |
+| database | agentrun_v02 | agentrun_release |
+| kafka client-id | agentrun-v02-manager | agentrun-release-manager |
+| secret target ns | agentrun-v02 | agentrun-release |
+| maxRunners | 20 | 10 |
+
+## 非本阶段
+
+未部署 release manager、未创建 PaC consumer、未建独立 DB 实例、未切 HWLAB 流量。
@@ -0,0 +1,19 @@
+# R1.4 任务报告
+
+## 验证
+
+```bash
+bun scripts/cli.ts agentrun control-plane plan --node NC01 --lane nc01-v02
+# NAMESPACE agentrun-v02 SOURCE v0.2 CHECKS 8
+
+bun scripts/cli.ts agentrun control-plane plan --node NC01 --lane nc01-release
+# NAMESPACE agentrun-release SOURCE release CHECKS 8
+
+trans NC01:k3s kubectl get ns agentrun-release
+# Active
+```
+
+## 结论
+
+- release lane 可解析；dev plan 无回归。
+- namespace / DB 名 / kafka client-id / secret target ns 均隔离。
@@ -0,0 +1,24 @@
+# R1 任务报告
+
+## 目标
+
+建立 AgentRun production 的 **namespace 隔离骨架**（#2154 R1）。
+
+## 已完成
+
+1. Issue #2154 + MDTODO `agentrun-dev-production-lanes`
+2. NC01 创建 `agentrun-release` Namespace
+3. YAML 声明 `nc01-release` lane（与 `nc01-v02` 并列）
+4. plan 双 lane 可跑；dev 无回归
+
+## 未做（后续 R2–R7）
+
+模板参数化、PaC/GitOps、独立 DB 物化、manager 上线、HWLAB 绑定、文档全量收敛。
+
+## 关键命令
+
+```bash
+trans NC01:k3s kubectl get ns agentrun-release
+bun scripts/cli.ts agentrun control-plane plan --node NC01 --lane nc01-release
+bun scripts/cli.ts agentrun control-plane plan --node NC01 --lane nc01-v02
+```
@@ -0,0 +1,12 @@
+# R3 任务报告
+
+## 完成
+
+- `config/platform-infra/pipelines-as-code.yaml`：`agentrunRelease` repository/consumer 模板 + NC01 实例 `agentrun-nc01-release`
+- `config/platform-infra/gitea.yaml`：mirror key `agentrun-nc01-release`（branch `release`，gitops `nc01-release-gitops`）
+- control-plane 对象已 apply：Tekton SA/Role/Pipeline、Argo AppProject（Application 因 gitops 分支未解析保持 ComparisonError，已去掉 automated sync 防误伤 bootstrap）
+
+## 未完成
+
+- agentrun 仓创建 `release` / `nc01-release-gitops` 与 `.tekton/agentrun-nc01-release.yaml`
+- PaC Repository CR / webhook 在集群侧 bootstrap（consumer 权威已可解析）
@@ -0,0 +1,8 @@
+# R4 任务报告
+
+## 完成
+
+- host PostgreSQL 创建 role/database `agentrun_release`
+- owner secret：`agentrun/nc01-release-mgr-db.env`（不入库）
+- `secret-sync --lane nc01-release --confirm`：16 个 secret 就绪（2 个 omitted 非阻塞）
+- 独立 target namespace：`agentrun-release`
@@ -0,0 +1,14 @@
+# R5 任务报告
+
+## 完成
+
+- 渲染 `runtime-release` mgr/runner-rbac 并 server-side apply
+- 镜像复用现网 env digest `sha256:e080ba9a…`（与 v02 同构建物，namespace/DB 隔离）
+- Deployment `agentrun-mgr` Ready 1/1
+- `/health/live` 与 `/health/readiness`：`live=true ready=true`，DB migration `013_v02_runner_dispatch_outcome` ready
+- 内网 Service：`agentrun-mgr.agentrun-release.svc.cluster.local:8080`
+- v02 manager 仍 Ready 1/1
+
+## 说明
+
+bootstrap 字段 manager：`unidesk-agentrun-release-bootstrap`；后续以 GitOps 为准时需在 agentrun 仓写入 runtime-release 并由 PaC 推进。
@@ -0,0 +1,50 @@
+# R5.10 P0 事故复盘
+
+## 结论
+
+本次事故不是生产 lane writer 修改开发环境，也不是数据库迁移依赖。真正根因是一个此前被 admission 阻塞的旧 AgentRun PaC PipelineRun，在较新 `b258520` 已成功发布后才开始执行，并以较新的 GitOps commit 为父提交，把 `sourceCommit` 逆序写回旧值 `0ca2c73`。Argo 正常同步了错误 desired，manager 因此重新加载旧 `sub2api` Artificer AipodSpec，新任务在 admission 阶段失败。
+
+## 影响
+
+- NC01/nc01-v02 manager desired 与源码 `v0.2` 分叉。
+- Artificer 从 `gpt-pika/grok` 回退到已删除的 `sub2api` provider。
+- HWLAB 公网入口修复无法派单，主线被 CI/CD 运行面故障阻塞。
+- 两个重复的生产 lane writer 被停止；后续证据确认它们不是 `bc12e93` 的作者。
+
+## 时间线
+
+- 较新 PipelineRun `agentrun-nc01-v02-ci-b258520...` 成功，生成 GitOps `dba70ac`。
+- 旧 `agentrun-nc01-v02-ci-0ca2...` 在 admission 解除后延迟启动，生成父提交为 `dba70ac` 的 `bc12e93`，但把 sourceCommit 写回 `0ca2c73`。
+- PR [UniDesk #2157](https://github.com/pikasTech/unidesk/pull/2157) 与 [AgentRun #364](https://github.com/pikasTech/agentrun/pull/364) 加入 stale/divergent/unverifiable revision 成功 no-op 逻辑。
+- #364 的自动 PipelineRun 在 `place-scripts` init 阶段失败；共享 schema validator 与 Ajv 被明文嵌入，单步脚本约 172 KiB，init container 退出 255。
+- PR [UniDesk #2160](https://github.com/pikasTech/unidesk/pull/2160) 将内嵌载荷改为 renderer 侧 gzip/base64，脚本降至 79,395 bytes；[AgentRun #365](https://github.com/pikasTech/agentrun/pull/365) 更新 repo-owned source artifact。
+- #365 merge 自动产生 PipelineRun `agentrun-nc01-v02-ci-5d7ede...`，成功生成 GitOps `56b5f3ed...` 并滚动 manager。
+
+## 根因与促成因素
+
+- promotion 缺少 incoming revision 相对 source branch 与当前 GitOps desired 的 ancestry/新旧判定，旧任务可以覆盖新 desired。
+- admission 阻塞把旧任务延迟到新任务之后执行，暴露了 PipelineRun 完成顺序不等于 source revision 顺序。
+- schema warning-only 实现把完整依赖明文嵌入 Tekton step，缺少对 place-scripts 载荷尺寸的运行面约束验证。
+- PaC `status/history/debug-step` 间歇性空 stdout，增加了定位成本；该可见性缺口由 [UniDesk #2165](https://github.com/pikasTech/unidesk/issues/2165) 独立跟踪，不改变交付 authority。
+
+## 修复
+
+- incoming revision 已过期、分叉或相对当前 desired 无法验证时，PipelineRun 保持成功终态、输出 `blocking=false` warning，并保留现有 GitOps commit。
+- ancestry 判断只使用 source clone 已有 refs 与当前 GitOps `source.json`，不增加第二 authority 或额外网络 fetch。
+- validator/Ajv 由 renderer 预压缩，运行时解压到有界临时文件；schema 与 OTel 失败仍只产生 warning，业务发布继续。
+- 全部恢复只由正常 PR merge 的 GitHub webhook -> Gitea -> PaC -> Tekton -> GitOps/Argo 自动链完成；未执行人工 PipelineRun、mirror sync、Argo sync、runtime patch 或数据库操作。
+
+## 验证
+
+- schema stage 定向 Bun 测试：5 pass，0 fail；未运行 Vitest。
+- AgentRun source artifact：aligned=true、provenance=true；生成 YAML 可解析，`gitops-promote` 脚本 `sh -n` 通过。
+- 自动 PipelineRun `agentrun-nc01-v02-ci-5d7ede...`：Succeeded。
+- GitOps commit：`56b5f3ed00f28b04e47f2e9baf3792d745d2a375`。
+- manager Deployment `AGENTRUN_SOURCE_COMMIT=5d7ede07543d6f8d9924ce9853420a4c6051eabd`，新 Pod ready。
+- `agentrun describe aipodspec/Artificer`：lane=`v0.2`、profile=`gpt-pika`、provider=`NC01`、model=`gpt-5.6-sol`，provider SecretRefs 为 `gpt-pika` 与 `grok`，旧 `sub2api` 已消失。
+
+## 长期判定
+
+- PipelineRun 的 source revision 决定新旧，排队与完成时间不能成为 desired authority。
+- runtime patch 可按 `$unidesk-daddev` P2 用于调试或临时恢复，但不能冒充终态；本事故未使用 patch，终态已由正常自动链收敛。
+- CI/CD 校验继续 warning-only，不得因 schema/OTel 漂移关闭功能或阻塞滚动。
@@ -0,0 +1,3 @@
+# R1.5.9.13.1 任务报告
+
+PaC admission provenance 漂移已按用户要求降级为非阻塞 warning。共享 Repository 与独立 consumer 可以完成 bootstrap，正常产品 PR merge 产生的 PipelineRun 不再被旧一致性门禁阻塞。
@@ -0,0 +1,3 @@
+# R1.5.9.13 任务报告
+
+已建立仅跟随产品 master 的 pikaoa-test-nc01 测试 CI/CD。正常产品 PR merge 自动触发测试 PipelineRun，测试 namespace 保持为 pikaoa-test，未触发生产 release consumer。测试 Web、API、Worker、数据库和完整合同/发票主路径均已验收。
@@ -0,0 +1,3 @@
+# R1.5.9 任务报告
+
+现有 NC01 k3s 已建立固定 pikaoa-test namespace，使用 PK01 host PostgreSQL 独立测试库与角色，并以 YAML 声明 NodePort 32080。CLI 单步部署、测试 CI/CD、桌面与移动 Web、合同多版本、发票关联及废弃、OTel 和 Prometheus 均已通过真实验收。
@@ -0,0 +1,3 @@
+# R1.6 任务报告
+
+双仓生产交付改动已审核合并。产品 release 的正常 PR merge 自动触发生产 PipelineRun，API、Worker、Web 镜像构建与 GitOps 发布全部成功；未人工创建 PipelineRun。
@@ -0,0 +1,3 @@
+# R1.7 任务报告
+
+生产原入口 https://oa.pikapython.com 已完成验收：TLS 与首页返回 200，管理员公网登录成功；员工、模块、伙伴、合同、发票与审计接口可用。公网写入验收完成甲方分类、伙伴、合同 v1/v2、关联发票与废弃，全部资源 ID 唯一且版本关系正确。桌面与 390x844 移动视口登录工作台通过且无页面或控制台错误。NC01 API、Web、Worker、FRPC 均 Ready 1/1，Argo 为 Synced/Healthy；Prometheus 生产 API/Worker 数据库就绪值均为 1，登录 trace 共 18 spans、0 error。
@@ -0,0 +1,3 @@
+# R1.8.1 任务报告
+
+已纠正 PikaOA 长期参考中“生产尚未 bootstrap”的过时事实，补充 release source authority、生产 namespace、PK01 数据库、fresh initializer、公网入口及非阻塞门禁边界。新增运行面、Argo、公网、Prometheus、桌面/移动 Web 与 OTel 的最短只读验收路径，使后续同类核查无需重新搜索生产状态和入口。
@@ -0,0 +1,3 @@
+# R1.8 任务报告
+
+PikaOA MVP issue、MDTODO 与生产验收报告已收口，测试与生产交付 issue 已关闭，主 issue 已追加上线证据。post-task 完成两项通用改进：PR #2161 固化生产最短只读验收路径；agent_skills PR #14 新增 Playwright fill-file 安全 Secret 填写入口并通过不泄露 smoke。已删除所有 clean 且被 master/release 吸收的 PikaOA worktree 和本地分支；未吸收的附件备份 worktree及存在用户修改的 Web worktree按保护规则保留。
@@ -78,3 +78,28 @@

 - 无源码或定向验证阻塞。
 - 运行面验收仍等待 PR 合并及主代理执行受控 bootstrap，因此任务保持 `in_progress`。
+
+## 启动 backlog 后续
+
+- warning-only admission 收敛后，新 PaC run 已可创建，但 NC01 官方 watcher 在重放历史 PipelineRun 时暴露第二断点：
+  - Pod `pipelines-as-code-watcher-7f6c87497c-7lhfh` 的 `/live` 在集中 reconcile 期间超过 `5s` timeout；
+  - 默认 liveness 在 `initialDelaySeconds: 5`、`failureThreshold: 3` 下连续失败并重启容器；
+  - 同期 readiness 失败只影响流量就绪，liveness 重启会反复打断历史 backlog 初始同步。
+- owning YAML 新增 `release.workloads.watcher`，明确声明：
+  - watcher Deployment 与 container identity；
+  - startup、readiness 与 liveness 三类 HTTP probe；
+  - startup backlog 窗口和 liveness 延迟全部由 YAML 持有，代码不提供隐藏数值默认值。
+- PaC bootstrap 下载官方 v0.48.0 release manifest 后，在 apply 前按 YAML 精确匹配 watcher Deployment/container 并渲染探针：
+  - 未匹配 Deployment 或 container 时直接失败；
+  - 不使用 runtime patch、第二份 manifest 或手工 `kubectl patch`；
+  - 后续官方 release reapply 仍由同一 bootstrap 渲染相同 desired state。
+- 启动窗口采用：
+  - startup：延迟 `30s`，每 `10s` 检查，单次 timeout `5s`，允许 `60` 次失败；
+  - liveness：延迟 `180s`，每 `10s` 检查，允许 `6` 次失败；
+  - readiness：保留 `5s` 延迟、`10s` 周期和 `3` 次失败，只控制就绪状态。
+- 定向验证：
+  - `bun test scripts/src/platform-infra-pipelines-as-code-bootstrap.test.ts`：`13 pass, 0 fail, 66 expect()`；
+  - 使用真实 v0.48.0 上游 manifest 验证：共解析 `35` 个对象，精确命中 `pipelines-as-code-watcher/pac-watcher` 并渲染三类 YAML-owned probe；
+  - `bun scripts/cli.ts platform-infra pipelines-as-code plan --target NC01 --consumer hwlab-nc01-v03 --json`：成功披露 watcher probes，`warnings=[]`；
+  - `git diff --check`：通过。
+- 合并后只允许由 PaC migrated consumer 的正常 PR merge 自动链触发交付；不得人工执行 PipelineRun、mirror、trigger、sync、flush、Argo sync、runtime patch 或删除历史业务对象。
@@ -0,0 +1,46 @@
+# R1 任务报告
+
+## 关联
+
+- 来源任务：[UniDesk #2133](https://github.com/pikasTech/unidesk/issues/2133)，MDTODO `R9.1`。
+- 改进 issue：[UniDesk #2153](https://github.com/pikasTech/unidesk/issues/2153)。
+- 后续语音主线：[UniDesk #2148](https://github.com/pikasTech/unidesk/issues/2148)，本改进不构成其门禁。
+
+## 问题判断
+
+R9.1 的远程 Docker GPU 实验需要多次手写后台 PID、status、log、证据和清理命令。仓库已有 60 秒短连接规则及专用 async 实现，但 `unidesk-trans` 没有面向一次性远程实验的参数化模板。
+
+已查重：
+
+- `#431/#435` 只处理 Playwright 专用 submit；
+- `#2148` 已吸收稳定 Torch/TorchAudio ABI 预检经验，但不是工具或 skill 改进；
+- 未发现覆盖通用临时 build、Docker GPU、模型下载和硬件 smoke 的重复 issue 或 MDTODO。
+
+## 交付
+
+- 新增 `.agents/skills/unidesk-trans/references/remote-experiment-smoke.md`：
+  - 定义 `route`、`work_dir`、`resource_prefix`、`job_id`、`command`、artifact allowlist 和停止条件；
+  - 提供一次 preflight；
+  - 提供 job 脚本、submit 和 bounded poll；
+  - 统一原入口 evidence 字段；
+  - 提供按 label 或资源前缀执行的幂等 cleanup；
+  - 明确网络、registry、ABI、OOM 和模型失败必须分层记录。
+- 更新 `unidesk-trans` skill 与 operation reference 索引。
+- 新增独立 MDTODO，避免把改进夹入 SelfMedia 业务任务。
+
+## 验证
+
+- 五个 Bash 代码块替换占位符后均通过 `sh -n`。
+- Markdown fence、reference 文件和 `git diff --check` 通过。
+- NC01 原入口完成一个真实最小 smoke：
+  - submit 返回 PID；
+  - poll 返回 `state=finished exit=0`；
+  - artifact 内容为 `template-smoke-ok`；
+  - stdout/stderr 均为 `0` bytes；
+  - cleanup 复查为 `clean`。
+
+## 边界
+
+- 未新增 CLI 子命令、后台服务、安全机制或正式运行面。
+- 未硬编码 Qwen、CosyVoice、D518、镜像、模型或端口。
+- 未修改 `#2148`，未触发 Docker、GPU、CI/CD 或 rollout。
@@ -89,7 +89,7 @@
 #### R1.5.8 [completed]

 修复 `pikaoa test-target` 临时运行面缺失附件配置与数据库迁移启动链，使 fixture 能渲染当前产品可启动的 namespace-local 后端运行面，保持未声明 target 与 `validationOnly` 全程无远端变更，执行记录见 [pikasTech/unidesk#2053](https://github.com/pikasTech/unidesk/issues/2053)，完成任务后将详细报告写入[任务报告](./details/pikaoa-enterprise-platform/R1.5.8_Task_Report.md)。
-#### R1.5.9 [in_progress]
+#### R1.5.9 [completed]

 按用户确认方案在现有 NC01 k3s 的独立 pikaoa-test namespace 建立 YAML-first 测试运行面，使用 PK01 host PostgreSQL 独立测试 database/role 和 YAML hostIP 端口；先通过受控 CLI 单步调通，再接入跟随产品 master 的独立测试 CI/CD，执行记录见 [pikasTech/unidesk#2058](https://github.com/pikasTech/unidesk/issues/2058)，完成任务后将详细报告写入[任务报告](./details/pikaoa-enterprise-platform/R1.5.9_Task_Report.md)。

@@ -129,13 +129,13 @@
 ##### R1.5.9.12 [completed]

 修复 PikaOA HTTP hostIP 测试入口因 crypto.randomUUID 不可用导致 Web 登录失败的问题，并完成桌面与移动端真实入口验收（pikainc/pikaoa#22），完成任务后将详细报告写入[任务报告](./details/pikaoa-enterprise-platform/R1.5.9.12_Task_Report.md)。
-##### R1.5.9.13 [in_progress]
+##### R1.5.9.13 [completed]

 接入仅跟随产品 master 的 pikaoa-test-nc01 独立测试 CI/CD，通过正常 source PR merge 自动交付 NC01 pikaoa-test，保持生产 consumer 不触发（pikasTech/unidesk#2105），完成任务后将详细报告写入[任务报告](./details/pikaoa-enterprise-platform/R1.5.9.13_Task_Report.md)。
-###### R1.5.9.13.1 [in_progress]
+###### R1.5.9.13.1 [completed]

 修复 PikaOA 首次 PaC bootstrap 未同步 admission provenance desired policy/binding 的缺口，使配置指纹漂移降级为非阻塞 warning 且正常产品 PR merge 产生的 PipelineRun 能继续执行，执行记录见 [pikasTech/unidesk#2127](https://github.com/pikasTech/unidesk/issues/2127)，完成任务后将详细报告写入[任务报告](./details/pikaoa-enterprise-platform/R1.5.9.13.1_Task_Report.md)。
-### R1.6
+### R1.6 [completed]

 审核并合并双仓 PR，执行首次受控 PaC bootstrap，由正常 source PR merge 自动发布，依赖 R1.3-R1.5，完成任务后将详细报告写入[任务报告](./details/pikaoa-enterprise-platform/R1.6_Task_Report.md)。

@@ -151,10 +151,14 @@
 ##### R1.6.1.3 [completed]

 建立仅跟随产品 release 的 PikaOA 生产 PaC/Tekton/GitOps/Argo lane，以 fresh initializer 在 NC01 pikaoa namespace 启动 API/Worker/Web/附件 PVC，接入 PK01 host PostgreSQL、OTel/Prometheus 和 oa.pikapython.com TLS 公网入口，执行记录见 [pikasTech/unidesk#2129](https://github.com/pikasTech/unidesk/issues/2129)，完成任务后将详细报告写入[任务报告](./details/pikaoa-enterprise-platform/R1.6.1.3_Task_Report.md)。
-### R1.7
+### R1.7 [completed]

 通过 CLI、OTel、Prometheus 和 https://oa.pikapython.com 桌面/移动原入口验证完整主路径，依赖 R1.6，完成任务后将详细报告写入[任务报告](./details/pikaoa-enterprise-platform/R1.7_Task_Report.md)。

-### R1.8
+### R1.8 [completed]

 完成 issue、MDTODO、阶段报告、post-task、已吸收 worktree 与分支清理，依赖 R1.7，完成任务后将详细报告写入[任务报告](./details/pikaoa-enterprise-platform/R1.8_Task_Report.md)。
+
+#### R1.8.1 [completed]
+
+更新 PikaOA 生产上线后的长期参考与最短只读验收路径，纠正“生产尚未 bootstrap”的过时事实并关联 [pikasTech/unidesk#2159](https://github.com/pikasTech/unidesk/issues/2159)，完成任务后将详细报告写入[任务报告](./details/pikaoa-enterprise-platform/R1.8.1_Task_Report.md)。
@@ -0,0 +1,9 @@
+## R1 [completed]
+
+依据 [UniDesk #2153](https://github.com/pikasTech/unidesk/issues/2153) 为 `unidesk-trans` 增加参数化远程临时实验 smoke 模板：
+
+- 统一一次 preflight、后台 job submit/poll、原入口 evidence、停止条件和幂等 cleanup；
+- 不得硬编码节点、模型、镜像或端口；
+- 不新增 CLI 子命令；
+- 不阻塞 SelfMedia R9.1.1；
+- 完成任务后将详细报告写入[任务报告](./details/trans-remote-experiment-smoke/R1_Task_Report.md)。
@@ -55,7 +55,7 @@
 - 分流顺序：

  - 可复用工作流进入 skill `SKILL.md`，例如：
-    - `$dad-dev`、`$unidesk-cicd`、`$unidesk-gh`；
+    - `$unidesk-daddev`、`$unidesk-cicd`、`$unidesk-gh`；
    - `$unidesk-trans`、`$unidesk-otel`、`$unidesk-webdev`；
    - `$unidesk-ymalops`。
  - 稳定项目约束、工作区规则、架构边界和验收标准进入 `docs/reference/*.md`。
@@ -132,7 +132,7 @@
 - CLI 行为与输出：`docs/reference/cli.md`。
 - YAML-first 配置：`docs/reference/yaml-first-ops.md` 与 `$unidesk-ymalops`。
 - 平台基础设施：`docs/reference/platform-infra.md`；涉及 Sub2API 时使用 `$unidesk-sub2api`。
- 分布式现场修复：`$dad-dev` 与 `docs/reference/devops-hygiene.md`。
+- 分布式现场修复：`$unidesk-daddev` 与 `docs/reference/devops-hygiene.md`。
 - CI/CD 与发布：`$unidesk-cicd` 与 `docs/reference/cli.md`。
 - GitHub issue 与 PR 写入：`$unidesk-gh`。
 - Trans/远端补丁传输：`$unidesk-trans` 与 `docs/reference/cli.md`。
@@ -46,26 +46,41 @@ AgentRun 源码仓目标 branch 的任何变更都必须通过 GitHub PR 合并

 ## 部署目标

-AgentRun 废弃旧 `dev/prod` 和非 NC01 node 运行口径。固定部署目标是 NC01 k3s 的 AgentRun namespace：
+AgentRun 固定在 NC01 k3s，按 **namespace 隔离** 拆分 development / production 两条 lane（同集群，非独立物理集群）。身份真相是 `config/agentrun.yaml#controlPlane.lanes`；跟踪见 [UniDesk #2154](https://github.com/pikasTech/unidesk/issues/2154)。
+
+| 角色 | Lane | Namespace | Source branch | Workspace | 默认 |
+|------|------|-----------|---------------|-----------|------|
+| Development | `nc01-v02` | `agentrun-v02` | `v0.2` | `/root/agentrun-v02` | 是（`controlPlane.default.lane`） |
+| Production | `nc01-release` | `agentrun-release` | `release` | `/root/agentrun-release` | 否，必须显式 `--lane nc01-release` |

 ```text
-NC01:k3s namespace agentrun-v02
+NC01:k3s namespace agentrun-v02        # development runtime
+NC01:k3s namespace agentrun-release   # production runtime（manager 已上线；内网 ClusterIP）
 ```

+- production 内网入口：`http://agentrun-mgr.agentrun-release.svc.cluster.local:8080`
+- production DB：host PostgreSQL 独立库 `agentrun_release`（与 `agentrun_v02` 隔离）
+- production PaC consumer：`agentrun-nc01-release`（YAML 已声明；`nc01-release-gitops` 分支与自动链待 agentrun 仓补齐）
+- 当前 production manager 可由 YAML 渲染 manifest 做 bootstrap 上线；完整 PR merge → GitOps 自动链仍属 #2154 后续收敛
+
 所有 k3s 操作必须使用 UniDesk route 语法：

 ```bash
 trans NC01:k3s kubectl get pods -n agentrun-v02
+trans NC01:k3s kubectl get ns agentrun-release
+bun scripts/cli.ts agentrun control-plane plan --node NC01 --lane nc01-v02
+bun scripts/cli.ts agentrun control-plane plan --node NC01 --lane nc01-release
 ```

 不得把临时 NodePort、host port、pod IP、provider-gateway 业务 HTTP proxy 或一次性 port-forward 固化为 AgentRun 部署路径。任何公网入口、UniDesk/HWLAB 集成入口或跨服务访问路径，都必须先通过 AgentRun 仓库内经过审查的变更引入；UniDesk 只在后续记录对应运维入口。

 ## 受控 CI/CD 入口

-AgentRun 目标必须从 `config/agentrun.yaml` 解析，不得从 service repo 的 `deploy.json` 或 URL 片段推断。Delivery authority 还必须与 `config/platform-infra/gitea.yaml`、`config/platform-infra/pipelines-as-code.yaml` 的 consumer/repository 组合校验。当前默认 `NC01/nc01-v02` 是 PaC migrated consumer；目标 source branch 的 GitHub PR merge 是唯一正式交付触发。
+AgentRun 目标必须从 `config/agentrun.yaml` 解析，不得从 service repo 的 `deploy.json` 或 URL 片段推断。Delivery authority 还必须与 `config/platform-infra/gitea.yaml`、`config/platform-infra/pipelines-as-code.yaml` 的 consumer/repository 组合校验。当前默认 `NC01/nc01-v02` 是 PaC migrated consumer；目标 source branch 的 GitHub PR merge 是唯一正式交付触发。`nc01-release` 的独立 PaC consumer 属于 #2154 后续阶段，R1 仅完成 namespace 与 lane 声明。

 ```bash
-bun scripts/cli.ts agentrun control-plane status
+bun scripts/cli.ts agentrun control-plane status --node NC01 --lane nc01-v02
+bun scripts/cli.ts agentrun control-plane status --node NC01 --lane nc01-release
 bun scripts/cli.ts platform-infra pipelines-as-code status --target NC01 --consumer agentrun-nc01-v02
 bun scripts/cli.ts platform-infra pipelines-as-code history --target NC01 --consumer agentrun-nc01-v02 --limit 10
 bun scripts/cli.ts agentrun control-plane cleanup-runners --node NC01 --lane nc01-v02 --dry-run
@@ -60,9 +60,31 @@ If a manual repair is needed to unblock the platform, the durable fix must be co

 ## 分布式敏捷流程

-“分布式敏捷”是 UniDesk 对 distributed agile field repair 的固定流程名；通用 P1/P2/P3/P4 阶段、禁止行为和证据边界由 `$dad-dev` skill 维护，本参考不再重复展开。UniDesk 项目内只保留下面的特有约束：必须使用结构化 `trans`/UniDesk CLI 进入真实 provider、pod、host bridge 或 service port；运行面热补只能证明方向或临时恢复，不能成为隐藏部署真相；持久化完成必须回到 Git/PR/CI/CD 后原入口复测。
+“分布式敏捷”是 UniDesk 对 distributed agile field repair 的固定流程名；通用 P1/P2/P3/P4 阶段、禁止行为和证据边界由 `$unidesk-daddev` skill 维护，本参考不再重复展开。UniDesk 项目内只保留下面的特有约束：

-固定主 repo 是 source truth anchor，不是源码/运行面 scratch 区。会产生源码、配置、issue closeout、部署脚本、验收产物或高风险 dad-dev / post-task 交付的工作，执行前必须先从目标 fixed repo 的最新 remote/base 创建任务专属 `.worktree/<task>`，后续编辑、验证、提交、push 和受控 CLI 写操作都在该 worktree 内完成。UniDesk 任务 worktree 必须通过 `bun scripts/cli.ts dev-env worktree add .worktree/<task> --branch <branch> [--from origin/master]` 创建，让 `.worktreecopy` 白名单内的本地配置自动复制到新 worktree；fixed repo 只用于 `git fetch`、`git status`、快进同步、读取规则和这个受控创建入口。其中已有的并行未提交修改默认保持不动，不纳入当前任务，也不要用 reset、checkout 或删除来“清理”。
+- 必须使用结构化 `trans`/UniDesk CLI 进入真实 provider、pod、host bridge 或 service port；
+- P2 允许按调试需要实施最小、可逆的运行面 patch 或热补，
+  但它只能证明方向或临时恢复，不能成为隐藏部署真相、第二 authority、
+  GitOps desired、自动交付成功或最终验收证据；
+- P3 必须把有效变化写回 owning YAML、源码或 renderer，
+  经正常 PR 与自动 CI/CD/GitOps 交付；临时 patch 必须撤销，
+  或由已确认的声明式交付覆盖；
+- P4 使用用户原入口复测，不能用单次手工成功替代终态。
+
+固定主 repo 是 source truth anchor，不是源码/运行面 scratch 区。
+
+- 会产生源码、配置、issue closeout、部署脚本、验收产物，
+  或高风险 unidesk-daddev / post-task 交付的工作，
+  执行前必须从目标 fixed repo 的最新 remote/base
+  创建任务专属 `.worktree/<task>`；
+- 后续编辑、验证、提交、push 和受控 CLI 写操作都在该 worktree 内完成；
+- UniDesk 任务 worktree 必须通过
+  `bun scripts/cli.ts dev-env worktree add .worktree/<task> --branch <branch> [--from origin/master]`
+  创建，让 `.worktreecopy` 白名单内的本地配置自动复制到新 worktree；
+- fixed repo 只用于 `git fetch`、`git status`、快进同步、读取规则
+  和这个受控创建入口；
+- 其中已有的并行未提交修改默认保持不动，不纳入当前任务；
+- 禁止用 reset、checkout 或删除来“清理”。

 The root UniDesk checkout at `/root/unidesk` is the fixed main worktree and must stay on `master`. Non-`master` work belongs in a task-specific `.worktree/<task>`. Unexpected local changes are presumed to belong to another concurrent task: preserve them, do not reset, checkout, delete or rewrite them, and scope the current task's commit to its own files.

@@ -90,7 +112,7 @@ CONSTAR、控之星、71-FILTER、71-FREQ、PLC 项目和 PLC 控制器任务是

 When UniDesk's own CLI, wrapper or controlled toolchain is repaired, merge the durable fix into `master` before relying on it for the original operation. The checkout that actually executes the tool must then contain that merged revision. If a fixed checkout cannot fast-forward because of unrelated changes, preserve it and run the tool from a clean worktree based on current `origin/master`; never reset or overwrite concurrent work to update the executable path.

-在模型 provider、API provider、硬件链路、跨平台 bridge、CLI/trans/tran 或高频工具链问题上，判定外部 blocker 前仍需完成 UniDesk 的防误判核查：确认当前 runtime config / Secret key presence / env / proxy / NO_PROXY / endpoint / args，使用实际目标运行面复现，并尽量与 UniDesk/HWLAB 成熟实现对照。用户反馈或新证据推翻 blocker 判断时，立即切回 `$dad-dev` 的现场修复闭环。
+在模型 provider、API provider、硬件链路、跨平台 bridge、CLI/trans/tran 或高频工具链问题上，判定外部 blocker 前仍需完成 UniDesk 的防误判核查：确认当前 runtime config / Secret key presence / env / proxy / NO_PROXY / endpoint / args，使用实际目标运行面复现，并尽量与 UniDesk/HWLAB 成熟实现对照。用户反馈或新证据推翻 blocker 判断时，立即切回 `$unidesk-daddev` 的现场修复闭环。

 如果某个现场步骤因为 quoting、route 定位、kubeconfig、输出体积或缺少 helper 而反复痛苦，优先改进 UniDesk passthrough / CLI 并在本文件的 `Distributed Command Passthrough` 或 `docs/reference/cli.md` 中记录稳定入口，不要沉淀一批一次性 shell 菜谱。

@@ -35,7 +35,7 @@ The shared Prometheus stack may discover application monitors across namespaces

 ## GitOps And Control Plane

-Monitoring infrastructure must be declared as Git-backed desired state and applied through a controlled UniDesk or G14 GitOps path. A temporary `kubectl apply` may be used only as a `$dad-dev` P2 experiment; it must be followed by a durable source change and GitOps/CLI validation.
+Monitoring infrastructure must be declared as Git-backed desired state and applied through a controlled UniDesk or G14 GitOps path. A temporary `kubectl apply` may be used only as a `$unidesk-daddev` P2 experiment; it must be followed by a durable source change and GitOps/CLI validation.

 Current durable control surface:

@@ -92,7 +92,7 @@ Durable validation after rollout must prove:
 - No public HWLAB or UniDesk FRP endpoint exposes raw Prometheus, Grafana or application `/metrics`.
 - CLI or controlled proxy output can answer a bounded query and reports the target namespace/lane/source of the data.

-Metrics are supporting observability evidence. They do not replace `$dad-dev` source-level tests, CI/CD provenance or original-entry validation for HWLAB issues.
+Metrics are supporting observability evidence. They do not replace `$unidesk-daddev` source-level tests, CI/CD provenance or original-entry validation for HWLAB issues.

 ## Application Closeout Contract

@@ -6,7 +6,7 @@

 - HWLAB 固定运行面、工作区、原入口验收与凭据边界：`docs/reference/hwlab.md`。
 - Gitea source authority、PaC/Tekton、GitOps/Argo 与自动交付边界：`docs/reference/platform-infra.md#gitea-与-pipelines-as-code-边界`。
- 跨节点现场调查、持久化和原入口复测：`$dad-dev`。
+- 跨节点现场调查、持久化和原入口复测：`$unidesk-daddev`。
 - CI/CD 只读观察、scoped help 与 legacy 判定：`$unidesk-cicd` 及其按需 reference。
 - 固定开发机、Master 构建限制和任务 worktree：`docs/reference/dev-environment.md`。

@@ -7,7 +7,20 @@
 - UniDesk 指挥侧 workspace：`/root/unidesk`，固定使用 `master`，开始前执行 `git status` 和 `git pull --ff-only origin master`。
 - HWLAB 开发、部署和验证固定只使用 NC01。`config/hwlab-node-lanes.yaml` 是 node、lane、workspace、CI/CD repo、namespace、GitOps path、公网入口和 Secret sourceRef 的配置真相，当前默认目标必须是 `NC01/v03`。
 - HWLAB 固定主 workspace 是 `NC01:/root/hwlab-v03`，固定跟踪 `v0.3`。源码修改、PR 准备、repo 内验证、GitOps render 和 rollout 修复都必须在该固定 workspace 下创建任务级 `.worktree/<task>`；master server 本地 `/root/HWLAB`、一次性 clone、runner clone、pod 内副本或非 NC01 workspace 只能做只读对照，不能承担开发 source truth。
- HWLAB v0.3 delivery authority 由 `config/hwlab-node-lanes.yaml`、`config/platform-infra/gitea.yaml` 与 `config/platform-infra/pipelines-as-code.yaml` 组合确认。NC01/v03 精确解析为 PaC consumer 后，目标 branch 的 GitHub PR merge 是唯一交付触发；完整自动链为 GitHub webhook -> Gitea controlled mirror -> immutable snapshot -> Gitea webhook -> PaC -> Tekton -> GitOps/Argo -> runtime。默认 help、status 与 Next 只给只读 status/history；自动链故障必须修 owning YAML、controller 或源码，不得用 trigger、refresh、mirror sync/flush、人工 PipelineRun 或直接 Gitea push 补齐。
+- HWLAB v0.3 delivery authority：
+  - 由 `config/hwlab-node-lanes.yaml`、`config/platform-infra/gitea.yaml`
+    与 `config/platform-infra/pipelines-as-code.yaml` 组合确认；
+  - NC01/v03 精确解析为 PaC consumer 后，
+    目标 branch 的 GitHub PR merge 是唯一交付触发；
+  - 完整自动链为 GitHub webhook -> Gitea controlled mirror -> immutable snapshot
+    -> Gitea webhook -> PaC -> Tekton -> GitOps/Argo -> runtime；
+  - 默认 help、status 与 Next 只给只读 status/history；
+  - 自动链故障必须修 owning YAML、controller 或源码，
+    不得用 trigger、refresh、mirror sync/flush、人工 PipelineRun 或直接 Gitea push 补齐；
+  - 调试或临时恢复确需运行面 patch 时走 `$unidesk-daddev` P2；
+  - patch 不得改变交付 authority 或冒充终态；
+  - 结论必须写回 owning YAML/源码并由正常 PR 自动交付；
+  - 临时 patch 随后撤销或由声明式交付覆盖。
 - 进入任何 HWLAB 工作前，按 `NC01/v03` 解析 route/workspace/sourceBranch/kubeRoute/runtime namespace 做预检、快进和验证：工作面是 `NC01:/root/hwlab-v03`、source branch 是 `v0.3`、k3s route 是 `NC01:k3s`、runtime namespace 是 `hwlab-v03`、公网入口由 YAML 的 NC01 target 声明。
 - NC01 的 node-local registry 是 k3s workload/PVC，不是 host Docker registry。`hwlab nodes control-plane infra status --node NC01 --lane v03` 应显示 registry workload ready、PVC bound 和 endpoint ready；必须通过受控 `runtime-image preload` 和 `infra tools-image build/status` 补齐 BuildKit、runtime/base 和 tools image，再把 HWLAB/AgentRun status 与 web-probe smoke 作为可用性证据。
 - HWLAB 项目内长期规则入口仍以目标 repo 的 `AGENTS.md` 为准。进入已解析的目标 workspace 后，必须重新读取该 workspace 的规则文件；不能只凭主 server 的压缩上下文继续操作。
@@ -11,6 +11,16 @@
 - 测试 namespace 不根据 commit、instance 或任务动态生成。
 - `pikaoa` 与 `pikaoa-ci` 是正式交付保护 namespace。
 - 测试入口不得渲染、覆盖或删除保护 namespace 中的对象。
+- 生产运行面固定使用：
+  - source branch：`release`；
+  - consumer：`pikaoa-nc01`；
+  - runtime namespace：`pikaoa`；
+  - CI namespace：`pikaoa-ci`；
+  - Argo Application：`pikaoa-nc01`；
+  - 公网入口：`https://oa.pikapython.com`。
+- 生产交付与公网配置分别以以下 selector 为真相：
+  - `config/pikaoa.yaml#releaseRuntime.targets.NC01`；
+  - `config/pikaoa.yaml#delivery.targets.NC01`。

 ## 数据库边界

@@ -122,9 +132,49 @@
  - 不创建 namespace-local PostgreSQL；
  - 不把测试 CI/CD 变成生产交付或用户业务的阻塞门禁。
 - GitOps 接管后，手动 `test-target start|stop` mutation 仅用于暂停 Argo 自动同步后的有界调试；禁止 CLI direct-apply 与 Argo 同时写入。
- 生产 `pikaoa-nc01` 保留 `release` source authority，但当前不 bootstrap、不生成 `.tekton`、不创建 PipelineRun。
+- 生产 `pikaoa-nc01` 已完成 bootstrap：
+  - 产品 `release` 只生成 `.tekton/pikaoa-nc01-pac.yaml`；
+  - 正常 `release` PR merge 是生产 PipelineRun 的唯一触发入口；
+  - API、Worker、Web 并行构建并以 digest 发布到生产 GitOps branch；
+  - Argo Application `pikaoa-nc01` 自动同步 `pikaoa` namespace；
+  - 禁止人工补建 PipelineRun 代替 source merge。
+- 生产使用 PK01 host PostgreSQL 独立 `pikaoa` database/role，不使用 namespace-local PostgreSQL。
+- 生产初始化模式是 `fresh-database-only`，不实现旧数据迁移、兼容或回滚。
+- 版本、审计和配置一致性异常只产生 `blocking=false` warning，不作为 MVP 业务门禁。
 - PR、构建或单测不能替代固定 NodePort 原入口验收。

+## 生产最短只读验收
+
+- 先执行运行面与 Argo 对账：
+
+  ```bash
+  trans NC01:k3s kubectl get deploy,pod,svc,pvc -n pikaoa -o wide
+  trans NC01:k3s kubectl get application -n argocd pikaoa-nc01
+  ```
+
+- 运行面通过判定：
+  - API、Web、Worker、FRPC Deployment 全部 Ready；
+  - Pod 全部 Running 且没有新增重启；
+  - 附件 PVC 为 Bound；
+  - Argo 为 `Synced` 和 `Healthy`。
+- 再验证公网和共享可观测性：
+
+  ```bash
+  curl -fsSI https://oa.pikapython.com/
+  bun scripts/cli.ts platform-infra observability metrics-query \
+    --target NC01 \
+    --query 'pikaoa_database_ready' \
+    --full
+  ```
+
+- 公网与可观测性通过判定：
+  - 公网 HTTPS 返回 200；
+  - 生产 API 和 Worker 的 `pikaoa_database_ready` 均为 1；
+  - 使用 `$unidesk-webdev` 完成管理员桌面与移动视口登录；
+  - 使用 `$unidesk-otel` 查询登录 `traceId`，span error 数为 0。
+- 密码只从 owning YAML 声明的 `sourceRef` 读取，禁止出现在 CLI 参数、日志、截图或任务报告中。
+- 完整身份/RBAC、严格一致性审计和附件备份增强属于独立后续任务，不阻塞上述 MVP 验收。
+
 ## 本地验证

 - `config/fixtures/pikaoa-test-target.yaml` 只用于 renderer 和 CLI 测试。
@@ -15,7 +15,16 @@
 - Gitea mirror 与 Pipelines-as-Code 是 UniDesk 运维的 CI source/trigger 服务。`config/platform-infra/gitea.yaml` 和 `config/platform-infra/pipelines-as-code.yaml` 分别拥有 mirror/webhook 与 PaC Repository/consumer 配置；repo URL、snapshot、webhook、public exposure、FRP/Caddy port、token sourceRef 和 PaC params 不得隐藏在代码特例中。
 - Delivery authority resolver 必须组合上述两份 YAML，并按 consumer id、node、lane、upstream repository、branch 和 Gitea repository 精确关联。不得通过 URL 片段、repo 名称前缀或仓库专属 `if` 推断迁移状态。零匹配、多匹配和配置错误都必须返回 `unknown`、`mutation=false` 并停止生成或执行写操作。
 - PaC consumer 的唯一正式触发是目标 source branch 的 GitHub PR merge。完整自动链固定为：GitHub PR merge -> GitHub webhook -> Gitea controlled mirror -> immutable snapshot -> Gitea webhook -> PaC/Pipelines-as-Code -> Tekton -> GitOps/Argo -> runtime 运行面。
- PR 合并后，主代理、子代理和操作者都不得用 `apply`、`closeout`、`trigger-current`、`refresh`、`sync`、`flush`、`webhook-test`、人工 PipelineRun、直接 Gitea push、本地 mirror 写入或其他补跑完成当前交付。自动链不通时必须修 owning YAML、controller 或源码，并只用修复 PR 合并产生的新正常自动事件验收。
+- PR 合并后的交付边界：
+  - 主代理、子代理和操作者不得用 `apply`、`closeout`、`trigger-current`、
+    `refresh`、`sync`、`flush`、`webhook-test`、人工 PipelineRun、
+    直接 Gitea push、本地 mirror 写入或其他补跑完成当前交付；
+  - 自动链不通时必须修 owning YAML、controller 或源码，
+    并只用修复 PR 合并产生的新正常自动事件验收；
+  - 必要的运行面调试或临时恢复可以走 `$unidesk-daddev` P2 最小可逆 patch；
+  - patch 不得修改 source/ref authority、制造交付成功或替代终态；
+  - 成立的变化必须写回 owning YAML/源码并经正常 PR 自动交付；
+  - 临时 patch 随后撤销或由声明式交付覆盖。
 - Migrated consumer 的默认 help、status、`Next` 与 `REPAIR` 只能给 `status`、`history`、`events`、`logs`、只读单步下钻以及本节稳定引用。CLI 必须省略 mutation command，而不是只给命令加警告文字。`unknown` authority 同样 fail-closed。
 - 旧 `trigger-current`、`refresh` 和 mirror `sync|flush` 只允许在 owning YAML 明确解析为 `legacy-manual` 后执行，并且只在显式 `legacy-cicd` 或 `legacy-ops` scoped help 中可发现。平台 bootstrap、Secret 与配置维护属于独立职责，只在 `platform-bootstrap` 或 `platform-maintenance` scoped help 中展示，不能作为 source delivery recovery。
 - `closeout` 仅保留只读历史/诊断兼容入口，并且只能从 `compatibility-diagnostics` scoped help 发现。会 POST hook test 的 `webhook-test` mutation 入口已经删除；连通性只能通过真正只读的 status、GET 与 readiness 观察，禁止制造伪 push。