docs: govern renderer rollout scope

2026-07-21 11:34:11 +02:00
parent 3452b7907d
commit 04ec96651b
3 changed files with 16 additions and 0 deletions
@@ -155,6 +155,11 @@ L2 与 L3 发布必须使用 `plan -> 人工审阅 -> trigger` 的受控手动

 范围相对 owning YAML 声明的发布意图扩大时，`plan` 必须明确列出新增项。操作者应先修正源码、配置或 planner，使范围回到预期后重新生成计划；不得通过确认参数、白名单、忽略 warning 或扩大资源预算继续触发。

+- Renderer rollout 范围必须对应实际 GitOps Pod template diff：
+  - renderer 重建完整 runtime tree 并改写未选 workload 的 source identity 时，`plan` 必须把全部实际受影响 workload 计入 rollout；
+  - 只有未选 workload 的 manifest 和 source identity 均保持不变时，才允许显示局部 rollout；
+  - renderer 入口拆分到子模块后，全部参与 runtime materialization 的源码路径仍必须属于 planner 的 renderer 输入集合。
+
 唯一 mutation 是受控手动 `trigger`。它必须显式选择 target、lane、精确 source commit 和 pipeline intent，并向 PaC 发送 webhook；PaC 从同一 source authority 创建 commit-pinned PipelineRun。触发前必须先审阅当前输入的 plan；计划输入或范围已变化时必须重新 plan。禁止 CLI 直建或裸创建 PipelineRun、由 PR 合并回调 trigger，或为兼容旧自动链保留第二入口。

 `trigger` 被 PaC 接收后，动态 `next` 必须指向同一 source commit 的只读 `delivery-observe`。不得引导旧 `closeout`、自动同步、人工 PipelineRun 或 Argo mutation；触发失败或输入变化时只能回到重新 plan。
@@ -86,6 +86,12 @@ CoreDNS 和 k3s 控制面使用 Kubernetes 系统关键优先级。Sub2API 和

 `plan` 必须针对精确 source commit 在一次只读输出中披露：YAML configRef、env identity、env reuse/build 判定、待构建镜像数量与服务列表、待 rollout 服务、全部受影响服务、范围基线、新增范围、触发层 concurrency、构建层 max parallel、批次数、step/sidecar 资源合同、priority class 和核心保护摘要。`status` 和 `diagnosis` 必须披露运行/排队 TaskRun 数与稳定意图键状态。共享读取超时只能投影为 warning 或 unavailable，不得把全部 consumer 伪装为真实失败。

+- Renderer 范围判定必须符合以下规则：
+  - renderer 输入或配置变化会重建完整 runtime tree，并改写未选 workload 的 source identity 时，`plan` 必须显示全部实际 rollout 服务；
+  - 镜像构建范围继续由 env、组件输入和 artifact provenance 独立决定；
+  - 禁止用局部源码影响范围替代实际 GitOps Pod template diff；
+  - 只有未选 workload 的 manifest 和 source identity 均保持不变时，才允许报告局部 rollout。
+
 ### 5.6 CI-RESOURCE-REQ-006 中心自动触发禁用

 中心 PaC owning YAML 必须声明 `deliveryTrigger.mode=manual-plan-confirm` 和 `deliveryTrigger.mechanism=pac-webhook`。PaC webhook 接收端继续作为唯一 PipelineRun 创建入口，但 Gitea push hook、PR merge callback、branch follower、poller 和其他自动发送方不得调用它；PR merge 后只允许 source mirror 或 authority 更新。受控 apply 必须删除或禁用 Gitea 自动 hook，并在 status 中把自动发送方启用视为配置漂移。