docs: add v0.1 lane specs

docs/reference/spec-v01-cicd.md

@@ -0,0 +1,125 @@
+# v0.1 CI/CD 与版本 Lane 规格
+
+本文是 AgentRun `v0.1` 独立 CI/CD、GitOps、namespace、registry 和发布验收规格。AgentRun 从 `v0.1` 开始废弃 `dev/prod` 管理口径，改为按 `v0.1`、`v0.2`、`v0.3` 版本 lane 滚动。
+
+## 设计目标
+
+- `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 或本地镜像当作发布真相。
+- 发布证据以 live runtime、Argo desired state、GitOps branch、Tekton 证据和干净 source workspace 顺序判断。
+
+## 固定命名
+
+| 对象 | v0.1 规格 |
+| --- | --- |
+| Source repo | `git@github.com:pikasTech/agentrun.git` |
+| Source branch | `v0.1` |
+| Source workspace | `G14:/root/agentrun-v01` |
+| Worktree root | `G14:/root/agentrun-v01/.worktree/{task}` |
+| Runtime namespace | `agentrun-v01` |
+| GitOps branch | `v0.1-gitops` |
+| Artifact catalog | `v0.1-gitops:deploy/artifact-catalog.v01.json` |
+| 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>` |
+| Argo CD AppProject | `argocd/agentrun-v01` |
+| Argo CD Application | `argocd/agentrun-g14-v01` |
+
+公网入口暂不作为 `v0.1` 必备规格。若后续需要 UniDesk/HWLAB 跨服务入口，必须在本仓库新增受审查的 ingress/FRP/edge spec，不得临时固化 NodePort、host port、pod IP 或一次性 port-forward。
+
+## 真相源
+
+`v0.1` 发布真相按以下顺序判断：
+
+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 终态。
+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` 发布通过证据。
+
+## Source 与 GitOps 分层
+
+`v0.1` source branch 可以包含：
+
+- 源码、测试、长期参考文档、人写配置和模板。
+- `deploy/deploy.json` 或等价 lane intent。
+- Kubernetes 模板、render 脚本、CI/CD helper 和 catalog schema。
+
+`v0.1` source branch 不得跟踪：
+
+- `deploy/artifact-catalog.v01.json`。
+- `deploy/gitops/g14/runtime-v01/**`。
+- Argo 实际消费的 rendered runtime desired state。
+- image digest、publish state、reuse evidence 或 CI 生成 rollout metadata。
+
+`v0.1-gitops` branch 必须包含：
+
+- `deploy/artifact-catalog.v01.json`，记录 image tag、digest、source commit、service identity、publish/reuse 状态。
+- `deploy/gitops/g14/runtime-v01/**`，作为 Argo CD 消费的 desired state。
+- 必要 generated metadata，但不得包含 Secret 值。
+
+首次初始化时，如果 `v0.1-gitops:deploy/artifact-catalog.v01.json` 尚不存在，只允许由 `v0.1` lane 的正式初始化步骤创建第一版 catalog。不得 fallback 到 `master`、`agentrun_dev`、`agentrun_prod` 或 source branch 生成物。
+
+## CI/CD 链路
+
+标准链路如下：
+
+1. `agentrun-v01-branch-poller` 轮询 `origin/v0.1`，按 source commit 创建 `agentrun-v01-ci-poll-<short12>` PipelineRun。
+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。
+
+## Artifact 与镜像身份
+
+- `v0.1` 镜像 tag 使用完整 40 位 source commitId。
+- Runtime manifest 必须使用 digest pin 作为部署身份。
+- 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。
+
+## Kubernetes 与 Argo 边界
+
+- `agentrun-v01` namespace 只能由 `v0.1` GitOps lane 管理。
+- `argocd/agentrun-v01` AppProject destination 只能包含 `agentrun-v01`。
+- `argocd/agentrun-g14-v01` source 必须指向 `v0.1-gitops:deploy/gitops/g14/runtime-v01`，destination 必须是 `agentrun-v01`。
+- `v0.1` Secret、ServiceAccount、RBAC、PVC、ConfigMap 和 runtime config 必须独立命名或 namespace scope；文档、issue、trace 和 report 只记录 SecretRef 名称与 key，不记录值。
+- `agentrun_dev` 和 `agentrun_prod` 不得作为 `v0.1` namespace、Argo destination、Pipeline target 或验收目标。
+
+## 手动和热修边界
+
+- 只读诊断可以通过 UniDesk route `G14:k3s` 查询 `agentrun-v01`。
+- 写操作必须走 `v0.1` CI/CD、GitOps 或仓库内受控 CLI；不得长期使用手工 `kubectl apply/patch/delete` 维持运行态。
+- 任何需要临时 live hotfix 的情况，必须先记录 issue/PR，说明原因、影响范围、回滚方式和后续固化路径。
+- 不得在 master server 构建镜像、运行重型测试或把本地 Docker image 当作发布真相。
+
+## 验收标准
+
+- `G14:/root/agentrun-v01` 为 `v0.1...origin/v0.1` 且 clean。
+- `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 来源。
+- Runtime manifest 使用 digest pin，catalog 记录完整 source commit 与 digest。
+- 发布完成后可通过 `G14:k3s` 读取 `agentrun-v01` Pod ready、service health 和对应 image digest。
+
+## 规格的实现情况
+
+| 规格项 | 状态 | 说明 |
+| --- | --- | --- |
+| `v0.1` source branch | 已建立 | `origin/v0.1` 存在。 |
+| `G14:/root/agentrun-v01` workspace | 已建立 | 固定工作区使用 `v0.1` 分支。 |
+| `agentrun-v01` namespace | 未实现 | 需要后续初始化。 |
+| `v0.1-gitops` branch | 未实现 | 需要后续初始化。 |
+| Tekton/Argo lane | 未实现 | 需要后续按本文补齐。 |
+| `dev/prod` 废弃口径 | 已定义 | 本文明确 `agentrun_dev` 和 `agentrun_prod` 不作为当前规格目标。 |