docs: 固化 PaC 分层验收与缓存判定

.agents/skills/unidesk-cicd/SKILL.md

@@ -168,6 +168,8 @@ bun scripts/cli.ts hwlab nodes control-plane legacy-cicd --help
 - PaC source artifact 必须遵循以下边界：
   - 由 `config/platform-infra/pipelines-as-code.yaml#consumers[].sourceArtifact` 显式声明；
   - 通过 `source-artifact plan|check|write|status|verify-runtime` 管理；
+  - 新增 service 后，不能只看 PaC plan 的 `buildServices`；必须确认 renderer 生成了对应 plan result、独立 build Task 和 collector 依赖，并在自动事件中看到实际 TaskRun；
+  - 修改 source artifact 引用的源码入口时，先以独立 PR 合并源码，使 target branch 提供精确 source identity，再从更新后的 target branch 执行 `source-artifact write --confirm`；renderer 返回 `aligned=true` 时禁止制造无语义的生成文件 PR；
   - `taskRunTemplate` 等运行事实归属 owning YAML，代码只负责校验和渲染；
   - desired 只来自 owning YAML 与共享 renderer，禁止从 live Pipeline/PipelineRun 反向导出；
   - `verify-runtime` 使用干净且 `HEAD` 等于完整 source commit 的独立 worktree；
@@ -181,6 +183,14 @@ bun scripts/cli.ts hwlab nodes control-plane legacy-cicd --help
   - 三者一致时才允许返回 `no-runtime-change` 和 `retained` provenance；
   - 仍要求 PipelineRun 成功、原 Argo `Synced/Healthy`、runtime ready、sha256 digest pin 与 health ready；
   - 证据缺失、冲突或 source commit 不匹配必须 fail-closed，不得等价为 delivery disabled，也不得伪造新 artifact、GitOps revision 或 runtime source commit。
+- PaC 自动事件的阶段判定必须分层：
+  - webhook `202` 只表示 durable admission；以 branch、snapshot 和 delivery `committed` 证明 source authority 已提交；
+  - source committed 后仍需唯一匹配 source commit 的 PipelineRun；PaC create timeout 不能表述为构建失败；
+  - PipelineRun `Completed` 后必须检查 promote 结果；`skipped-stale-source` 表示沿最新后继 source commit 继续验收，不表示当前提交已部署；
+  - GitOps push、Argo revision、Deployment ready 和原入口分别取证；任一上游成功不能替代下游收敛。
+- BuildKit cache import/export 只属于加速能力：
+  - 镜像构建、manifest/digest 和 push 仍可阻塞；
+  - registry cache export 必须使用 BuildKit 原生 `ignore-error=true` 或等价非阻塞配置，禁止在镜像已成功发布后仅因 cache 写入抖动把 TaskRun 判失败。
 - PaC `status|closeout|history` 的 `--json` 是有界 machine contract；`--full` 展开单条详情，`--raw` 才展开目标侧原始 payload。`history --id --full` 不得重复嵌套同一 rows/consumer payload或依赖 `/tmp/unidesk-cli-output` 才可读。
 - PaC `status` 必须在 `observability.readOnlyCapture.timeoutMs` 内完成：
   - 目标侧通过 `pac-status-progress` 披露最后阶段，CLI 将其投影为 `observation.remoteStage`；

docs/reference/platform-infra.md

@@ -97,7 +97,18 @@
 - source-artifact consumer 的最短验证顺序固定为：
   - 先执行 `source-artifact plan`，确认唯一 owner、source worktree 与预期漂移；
   - 再执行 `source-artifact write --confirm` 和一次 `source-artifact check`，提交生成文件后只由正常 source PR merge 触发交付；
+  - 新增 service 时同时核对 plan result、独立 build Task、collector 依赖和自动事件中的实际 TaskRun，不能用 `buildServices` 列表替代 Pipeline 结构证据；
+  - 被 renderer 引用的源码入口发生变化时，先合并源码 PR，再从 target branch 的精确 source identity 渲染；若 check 已 `aligned=true`，不得创建空刷新或无语义 PR；
   - 自动链终态后，在 clean exact-commit worktree 执行一次 `source-artifact verify-runtime`，同时证明源码、嵌入式 PipelineRun 与 provenance 对齐。
+- 自动交付的最短分层诊断顺序固定为：
+  - 用 Gitea webhook status 区分 HTTP response、durable admission 和 source authority `committed`；HTTP 失败后 refs 已精确提交时保留两类事实，不把旧 response 覆盖 committed proof；
+  - 用 source commit 精确关联 PipelineRun；source 已 committed 但 PipelineRun 不存在时，定位 PaC create/admission，不进入 Task 日志；
+  - PipelineRun 成功后读取 GitOps promote verdict；`skipped-stale-source` 必须沿最新后继 commit 继续，不能记为当前 commit 已部署；
+  - promote pushed 后依次确认 Argo revision、Deployment ready、Service 暴露边界和原入口，避免用任一上游成功替代下游验收。
+- BuildKit registry cache 只负责加速：
+  - image layers、manifest、digest 和 push 是交付事实；
+  - cache export 使用原生 `ignore-error=true` 或等价非阻塞语义；
+  - cache export 抖动不得在镜像已发布后制造业务构建失败或人工补跑需求。
 - GitHub 始终是 upstream write authority。Bridge 只允许 GitHub -> Gitea 更新 YAML 声明的 branch 与 immutable snapshot，不得反向写 GitHub，也不得增加 polling 或第二 trigger path。
 - 每个 target 必须使用 YAML 独立声明的 webhook path、bridge 与 FRP port；多个节点不得复用 hook URL。Public Gitea Web UI 与 webhook 只能通过明确 Caddy path routing 共享 hostname，k8s 内部 consumer 必须使用 ClusterIP URL。
 - Secret 或 ConfigMap 改变后，Gitea connector 的显式平台配置维护必须等待 workload rollout。成功写 Secret 不能证明 `frpc` 已加载新配置；端到端交付证据仍必须来自之后的新正常 PR merge。