docs: refine v0.1 policy and cicd specs

docs/reference/spec-v01-cicd.md

@@ -7,7 +7,8 @@
 - `v0.1` 是独立 lane，不复用 `agentrun_dev` 或 `agentrun_prod` 作为当前运行面。
 - 每条版本 lane 拥有独立 source branch、source workspace、GitOps branch、runtime namespace、artifact catalog、runtime path、CI pipeline 和发布验收。
 - `v0.1` 只能部署到 `agentrun-v01` namespace；`v0.2`、`v0.3` 后续使用自己的 namespace 和 GitOps 路径。
-- CI/CD 必须使用 G14 原生 k3s、Tekton/GitOps/Argo CD 或等价受控 lane；不得把 master server、D601 legacy、临时 clone、手工 Pod patch 或本地镜像当作发布真相。
+- CI/CD 必须使用 G14 原生 k3s、纯 Tekton Pipeline/Task/PipelineRun 和 Argo CD；不得引入自定义 runner、CI.json runner、长期自研 poller/reconciler、D601 legacy、临时 clone、手工 Pod patch 或本地镜像作为发布真相。
+- `v0.1` 的 CD 唯一手写真相源是 source branch 内的 `deploy/deploy.json`；Tekton 生成的 artifact catalog 和 Argo desired state 必须与 source branch 分离，只写入 `v0.1-gitops`。
 - 发布证据以 live runtime、Argo desired state、GitOps branch、Tekton 证据和干净 source workspace 顺序判断。
 
 ## 固定命名
@@ -24,10 +25,8 @@
 | Runtime path | `v0.1-gitops:deploy/gitops/g14/runtime-v01` |
 | Tekton namespace | `agentrun-ci` |
 | Tekton Pipeline | `agentrun-v01-ci-image-publish` |
-| Branch poller | `agentrun-v01-branch-poller` |
-| Control-plane reconciler | `agentrun-v01-control-plane-reconciler` |
 | Tekton ServiceAccount | `agentrun-v01-tekton-runner` |
-| PipelineRun prefix | `agentrun-v01-ci-poll-<short12>` |
+| PipelineRun prefix | `agentrun-v01-ci-<short12>` |
 | Argo CD AppProject | `argocd/agentrun-v01` |
 | Argo CD Application | `argocd/agentrun-g14-v01` |
 
@@ -40,7 +39,7 @@
 1. Live runtime：`agentrun-v01` namespace 中 Deployment/Job/Pod ready、事件、日志和 service health。
 2. Argo desired state：`argocd/agentrun-g14-v01` 的 revision、sync、health、source branch 和 runtime path。
 3. GitOps branch：`v0.1-gitops` 中的 `deploy/artifact-catalog.v01.json` 与 `deploy/gitops/g14/runtime-v01/**`。
-4. Tekton 执行证据：`agentrun-v01-branch-poller`、PipelineRun、TaskRun result、image digest 和 promotion 终态。
+4. Tekton 执行证据：PipelineRun、TaskRun result、image digest 和 promotion 终态。
 5. 干净 source workspace：`G14:/root/agentrun-v01`、`origin/v0.1`、render 脚本、deploy intent 和 `--no-write` 输出。
 
 旧 `master` 记忆、`/root/agentrun` 固定工作区、`agentrun_dev`、`agentrun_prod`、D601 legacy 路径、临时 worktree 或本地容器只能作为线索，不能作为 `v0.1` 发布通过证据。
@@ -50,7 +49,7 @@
 `v0.1` source branch 可以包含：
 
 - 源码、测试、长期参考文档、人写配置和模板。
-- `deploy/deploy.json` 或等价 lane intent。
+- `deploy/deploy.json`，这是 `v0.1` CD 唯一手写真相源。
 - Kubernetes 模板、render 脚本、CI/CD helper 和 catalog schema。
 
 `v0.1` source branch 不得跟踪：
@@ -68,18 +67,37 @@
 
 首次初始化时，如果 `v0.1-gitops:deploy/artifact-catalog.v01.json` 尚不存在，只允许由 `v0.1` lane 的正式初始化步骤创建第一版 catalog。不得 fallback 到 `master`、`agentrun_dev`、`agentrun_prod` 或 source branch 生成物。
 
+## CD 唯一手写真相源
+
+`deploy/deploy.json` 是 `v0.1` CD 的唯一手写真相源。它只承载人写 runtime intent，不承载任何 CI 构造物。
+
+允许写入 `deploy/deploy.json` 的内容：
+
+- service id、组件类型和是否参与 `v0.1` runtime。
+- replica、resource request/limit、health path、ports、env key、ConfigMap/SecretRef 名称和 key。
+- runtime namespace、ServiceAccount、RBAC intent、PVC intent、NetworkPolicy intent。
+- public/ingress intent 的声明占位；`v0.1` 默认不要求公网入口。
+
+禁止写入 `deploy/deploy.json` 的内容：
+
+- image tag、image digest、publish status、reuse evidence、PipelineRun id、TaskRun id。
+- GitOps branch revision、Argo sync revision、runtime generated manifest。
+- Secret 值、token、kubeconfig、SSH key 或任何 credential value。
+
+Tekton promotion 可以读取 `deploy/deploy.json` 来 render runtime desired state，但不得回写 source branch 或修改 `deploy/deploy.json`。所有自动构造物只允许写入 `v0.1-gitops` 的 `deploy/artifact-catalog.v01.json` 和 `deploy/gitops/g14/runtime-v01/**`。
+
 ## CI/CD 链路
 
 标准链路如下：
 
-1. `agentrun-v01-branch-poller` 轮询 `origin/v0.1`，按 source commit 创建 `agentrun-v01-ci-poll-<short12>` PipelineRun。
+1. 人工或受控 GitHub/UniDesk 入口为某个 `origin/v0.1` source commit 创建 Tekton `PipelineRun`；触发器可以是 Tekton Triggers 或手动 `PipelineRun`，但不能是长期自定义 runner。
 2. `prepare-source` checkout `v0.1` source，并从 `v0.1-gitops` 读取上一版 `deploy/artifact-catalog.v01.json`。
-3. 原语校验 task 只覆盖文档治理、spec 链接、轻量语法和必要单元测试；旧 `dev/prod` gate 不进入 lane。
-4. Planner 根据组件输入判断 affected/reused services。
-5. Affected service 通过 BuildKit 发布到 G14 本地 registry；reused service 复用 catalog digest。
-6. Promotion 刷新 `deploy/artifact-catalog.v01.json`，render `deploy/gitops/g14/runtime-v01/**`，只推送到 `v0.1-gitops`。
-7. `agentrun-g14-v01` 从 `v0.1-gitops:deploy/gitops/g14/runtime-v01` 同步到 `agentrun-v01`。
-8. 验收只观察 `agentrun-v01` runtime 和对应 service health。
+3. 原语校验 task 只覆盖文档治理、spec 链接、`deploy/deploy.json` schema、轻量语法和必要单元测试；旧 `dev/prod` gate 不进入 lane。
+4. Plan task 读取 `deploy/deploy.json` 与上一版 artifact catalog，判断 affected/reused services；planner 只能输出 TaskRun result 或临时 workspace 文件，不回写 source。
+5. Affected service 通过 Tekton Task 内的 BuildKit/kaniko/buildah 之一发布到 G14 本地 registry；reused service 复用 catalog digest。不得使用 Docker daemon、DIND 或仓库外自定义 runner。
+6. Promotion task 用 publish results 刷新 `deploy/artifact-catalog.v01.json`，并用 `deploy/deploy.json` render `deploy/gitops/g14/runtime-v01/**`，只推送到 `v0.1-gitops`。
+7. Argo CD Application `agentrun-g14-v01` 从 `v0.1-gitops:deploy/gitops/g14/runtime-v01` 同步到 `agentrun-v01`。
+8. 验收只观察 `agentrun-v01` runtime、Argo revision/sync/health 和对应 service health。
 
 ## Artifact 与镜像身份
 
@@ -88,6 +106,7 @@
 - Catalog 必须记录 lane、source branch、GitOps branch、source commitId、serviceId、image tag、digest、component identity 和 publish/reuse 状态。
 - 同一 source commit 对同一 service 应生成同一镜像；lane 差异放在 manifest、env、SecretRef、namespace、RBAC 和 runtime config 中，不 bake 进镜像。
 - `deploy/deploy.json` 只承载人写 runtime intent，不承载 digest、publish state 或 reuse evidence。
+- Source branch 不得因为 promotion 出现自动提交；若发布后 source branch 变化，必须是人工修改源码、测试、文档、模板或 `deploy/deploy.json`。
 
 ## Kubernetes 与 Argo 边界
 
@@ -100,7 +119,7 @@
 ## 手动和热修边界
 
 - 只读诊断可以通过 UniDesk route `G14:k3s` 查询 `agentrun-v01`。
-- 写操作必须走 `v0.1` CI/CD、GitOps 或仓库内受控 CLI；不得长期使用手工 `kubectl apply/patch/delete` 维持运行态。
+- 写操作必须走 Tekton PipelineRun、GitOps promotion、Argo CD 或仓库内受控 CLI；不得长期使用手工 `kubectl apply/patch/delete` 维持运行态。
 - 任何需要临时 live hotfix 的情况，必须先记录 issue/PR，说明原因、影响范围、回滚方式和后续固化路径。
 - 不得在 master server 构建镜像、运行重型测试或把本地 Docker image 当作发布真相。
 
@@ -110,6 +129,8 @@
 - `AGENTS.md` 和 `docs/reference/` 不得把 `agentrun_dev` 或 `agentrun_prod` 写成 `v0.1` 当前 namespace、Argo destination、Pipeline target 或验收目标；只允许在废弃说明和历史背景中提及。
 - `agentrun-v01` namespace 存在，且 `agentrun_dev`/`agentrun_prod` 不参与 `v0.1` 发布判定。
 - `v0.1-gitops` branch 和 `deploy/gitops/g14/runtime-v01` 成为 Argo desired state 来源。
+- `deploy/deploy.json` 是 CD 唯一手写真相源；source branch 不跟踪 artifact catalog、runtime generated manifests、digest 或 publish state。
+- Tekton/Argo 路径不包含自定义 runner、CI.json runner、长期自研 poller 或 control-plane reconciler。
 - Runtime manifest 使用 digest pin，catalog 记录完整 source commit 与 digest。
 - 发布完成后可通过 `G14:k3s` 读取 `agentrun-v01` Pod ready、service health 和对应 image digest。
 
@@ -121,5 +142,5 @@
 | `G14:/root/agentrun-v01` workspace | 已建立 | 固定工作区使用 `v0.1` 分支。 |
 | `agentrun-v01` namespace | 未实现 | 需要后续初始化。 |
 | `v0.1-gitops` branch | 未实现 | 需要后续初始化。 |
-| Tekton/Argo lane | 未实现 | 需要后续按本文补齐。 |
+| 纯 Tekton/Argo lane | 未实现 | 需要后续按本文补齐；不得引入自定义 runner。 |
 | `dev/prod` 废弃口径 | 已定义 | 本文明确 `agentrun_dev` 和 `agentrun_prod` 不作为当前规格目标。 |

docs/reference/spec-v01-services.md

@@ -41,8 +41,8 @@ Runner inbound API 只允许本地或私有诊断，不作为业务客户端入
 | First real backend | 具体 Agent backend | 保留，P0 | `v0.1` 必须至少证明一个真实 Agent backend；默认候选是 Codex。 | `spec-v01-backend-codex.md` |
 | AgentRun CLI | CLI/Job 工具 | 保留，P0 | JSON 输出、短返回、run/command/event/runner/backend 操作入口。 | `spec-v01-cli.md` |
 | Durable store | 数据存储 | 保留，P0 | 保存 runs、commands、events、runners、backends、leases；具体存储可从 file/sqlite/Postgres 起步，但必须有迁移边界。 | `spec-v01-state-store.md` |
-| Tenant policy boundary | 系统能力 | 保留，P0 | 显式承载 tenantId、projectId、workspaceRef、providerId、backendProfile、executionPolicy、traceSink。 | `spec-v01-tenant-policy.md` |
-| Observability | 系统能力 | 保留，P1 | event、trace、log、redaction、terminal status 和 failure kind 统一观察。 | `spec-v01-observability.md` |
+| Tenant policy boundary | Run schema 合同 | 保留，P0 | 作为 `Run` 的必填字段和最小校验存在，不做独立 policy engine；tenant 的业务授权仍由 UniDesk/HWLAB 判定。 | 并入 `spec-v01-agentrun-mgr.md` |
+| Observability | 最小事件/日志合同 | 保留，P0 子项 | 作为 manager/runner 的 event、terminal status、failureKind、logPath 和 redaction 最小合同，不拆独立观测系统。 | 并入 `spec-v01-agentrun-mgr.md`、`spec-v01-agentrun-runner.md` |
 | `agentrun-scheduler` | 长驻调度器 | Deferred | M1-M3 稳定后再实现自动 pending scan、capacity selection 和 runner Job 创建。 | `spec-v01-scheduler.md` |
 | 多 backend 路由 | 系统能力 | Deferred | `v0.1` 不做完整多 backend 调度，只保留 capability 模型。 | 后续版本 spec |
 | UI | 前端 | Deferred | `v0.1` 不要求独立 UI；UniDesk/HWLAB canary 可通过 CLI/API 验证。 | 后续版本 spec |
@@ -75,6 +75,35 @@ POST  /api/v1/commands/:commandId/ack
 
 `v0.1` 禁止用 SSE、WebSocket、long-polling 或长同步 `turn` 请求替代 durable resource 模型。客户端通过分页轮询观察进度。
 
+## Run Schema 和 Tenant 边界
+
+`v0.1` 不实现复杂 tenant policy engine，但每个 run 必须显式承载租户边界字段，避免后续 UniDesk/HWLAB canary 接入时无法追责或隔离。
+
+Run create 的最小字段合同：
+
+| 字段 | v0.1 规则 |
+| --- | --- |
+| `tenantId` | 必填，例如 `unidesk`、`hwlab`；只做 allowlist/schema 校验。 |
+| `projectId` | 必填，例如 `pikasTech/unidesk`、`pikasTech/HWLAB`。 |
+| `workspaceRef` | 必填，描述 source/worktree/workspace，不由 runner 猜测。 |
+| `providerId` | 必填，例如 `G14`、`D601`；只表示目标 provider，不直接授予权限。 |
+| `backendProfile` | 必填，例如 `codex`；`v0.1` 只要求一个真实 backend 闭环。 |
+| `executionPolicy` | 必填或由 manager 显式写入默认值，至少包含 sandbox、approval、timeout、network 和 secret scope。 |
+| `traceSink` | 字段必须存在；可以为 `null` 或显式 sink，表示标准事件是否需要镜像给 tenant。 |
+
+Manager 负责校验、保存和返回这些字段；runner 只能消费已保存的 run policy，不能自行扩大 workspace、network 或 secret scope。HWLAB live device mutation、UniDesk production deploy、GitHub issue/PR 写入等业务授权仍由 tenant 自己的入口判定，AgentRun 不把这些业务规则内建成通用门禁。
+
+## 最小 Observability 合同
+
+`v0.1` 不拆出独立 `spec-v01-observability.md`，也不建设通用日志平台。可观察性只作为 run 生命周期的一部分：
+
+- `events` 必须 append-only，并按 `seq` 分页读取。
+- 每个 run 必须最终写出 `terminal_status` 或明确的 non-terminal status。
+- runner 启动失败、backend 失败、policy/schema 失败必须写入结构化 `failureKind`。
+- CLI 启动本地 process 或 Kubernetes Job 时必须返回 `logPath` 或 Kubernetes job/pod identity。
+- event 和日志不得打印 Secret/token 值；只能记录 SecretRef、credential source 或 redacted marker。
+- redaction 规则只覆盖明显 credential、token、Authorization header 和 URL credential；复杂审计、集中 trace、metrics dashboard 推迟到后续版本。
+
 ## MVP 分期
 
 | 阶段 | 目标 | 验收重点 |