@colin4k1024/tsp 2.4.0 → 2.4.2

package/docs/runbooks/handoff-governance.md

@@ -0,0 +1,250 @@
+---
+version: "1.0.0"
+status: active
+created: 2026-04-02
+updated: 2026-04-17
+owner: 工程团队
+doc_tier: governance
+last_verified: 2026-04-17
+source_of_truth:
+  - ../../rules/handoff-contract.md
+  - ./team-command-output-contracts.md
+---
+
+# Handoff 治理文档
+
+本文档是平台全量 Agent 交接路径的可视化治理入口，覆盖主链串行、并行设计、Specialist 调用回路和反馈打回四类路径。
+
+相关文档：
+- [sub-agent-invocation-map.md](sub-agent-invocation-map.md) — 命令→Agent 映射
+- [agent-governance.md](agent-governance.md) — 统一管控策略
+- [handoff-contract.md](../../rules/handoff-contract.md) — 交接字段要求
+- [team-command-output-contracts.md](team-command-output-contracts.md) — 命令输出结构
+
+---
+
+## 1. 全量 Handoff 流程图
+
+### 1.1 主链路径（/team-* 串行）
+
+```mermaid
+flowchart TD
+    subgraph 主链串行
+        A["/team-intake<br/>tech-lead"] -->|PRD draft| B["/team-plan<br/>tech-lead"]
+        B -->|Requirement Challenge + Dynamic Discussion| C["/handoff<br/>tech-lead"]
+        C -->|handoff-ready| D["/team-execute<br/>FE / BE"]
+        D -->|Execute Log + 自测结果| E["/team-review<br/>qa-engineer"]
+        E -->|放行建议| F["/team-release<br/>devops-engineer"]
+        F -->|发布结果| G["tech-lead<br/>最终收口"]
+    end
+```
+
+### 1.2 并行设计路径（/team-plan 阶段）
+
+```mermaid
+flowchart TD
+    TL["tech-lead<br/>Requirement Challenge Session"] -->|分组| DS["Dynamic Discussion Group"]
+    DS -->|并行| AR["architect<br/>系统边界 + 接口"]
+    DS -->|并行| UX["ui-ux-designer<br/>交互流 + 设计 token"]
+    DS -->|并行| FE["frontend-engineer<br/>组件 + 响应式"]
+    DS -->|并行| BE["backend-engineer<br/>数据模型 + 异常路径"]
+    AR --> DRB["Design Review Board<br/>tech-lead 主持"]
+    UX --> DRB
+    FE --> DRB
+    BE --> DRB
+    DRB -->|对齐结论| TL2["tech-lead<br/>handoff-ready"]
+```
+
+### 1.2.1 动态分组规则
+
+`/team-plan` 不是固定四方并行的默认直通，而是先由 `tech-lead` 按任务特征组装最小讨论组，再决定是否进入并行设计：
+
+- 业务目标或范围不清时，先拉 `product-manager`、`project-manager`、`architect`
+- 架构、接口或数据模型变更时，必须拉 `architect`、`backend-engineer`、`project-manager`
+- UI 或体验变更时，必须拉 `product-manager`、`ui-ux-designer`、`frontend-engineer`
+- 全栈改动时，必须拉 `architect`、`frontend-engineer`、`backend-engineer`、`project-manager`
+- 每个参与角色都必须留下至少 1 条质疑记录，否则不得进入 `Design Review Board`
+
+### 1.3 Specialist 调用回路
+
+```mermaid
+flowchart LR
+    subgraph "Role → Specialist → Role"
+        RE1["backend-engineer"] -->|代码完成| CR["code-reviewer"]
+        CR -->|发现安全问题| SR["security-reviewer"]
+        SR -->|安全修复建议| RE1
+        CR -->|通过| RE1
+
+        RE2["frontend-engineer"] -->|代码完成| CR2["code-reviewer"]
+        CR2 -->|通过| RE2
+        CR2 -->|质量问题| RE2
+
+        QA["qa-engineer"] -->|需要 E2E| E2E["e2e-runner"]
+        E2E -->|测试结果| QA
+        QA -->|需要 TDD 补充| TDD["tdd-guide"]
+        TDD -->|测试建议| QA
+
+        BE_BUILD["backend-engineer"] -->|构建失败| BER["build-error-resolver"]
+        BER -->|修复建议| BE_BUILD
+
+        TL_PLAN["tech-lead"] -->|复杂规划| PL["planner"]
+        PL -->|规划结果| TL_PLAN
+    end
+```
+
+### 1.4 反馈与打回路径
+
+```mermaid
+flowchart TD
+    subgraph 反馈闭环
+        QA_R["qa-engineer<br/>发现 Bug"] -->|打回| FE_R["frontend-engineer"]
+        QA_R -->|打回| BE_R["backend-engineer"]
+        FE_R -->|修复后| QA_R
+        BE_R -->|修复后| QA_R
+
+        DRB_R["Design Review Board<br/>驳回设计"] -->|打回| AR_R["architect"]
+        DRB_R -->|打回| UX_R["ui-ux-designer"]
+        AR_R -->|修改后| DRB_R
+        UX_R -->|修改后| DRB_R
+
+        UC["Upstream Challenge<br/>质疑未解决"] -->|升级| TL_R["tech-lead"]
+        TL_R -->|仲裁结论| UC
+    end
+```
+
+### 1.5 端到端完整流程
+
+```mermaid
+flowchart TD
+    START["业务方需求"] --> INTAKE["/team-intake<br/>tech-lead"]
+
+    INTAKE -->|"upstream_challenge<br/>质疑业务目标"| INTAKE
+    INTAKE -->|涉及 UI| UXI["ui-ux-designer<br/>初步体验约束"]
+    UXI --> INTAKE
+    INTAKE --> PLAN["/team-plan<br/>tech-lead"]
+
+    PLAN -->|需求挑战会| RCS["PM + Architect + PM<br/>Requirement Challenge"]
+    RCS --> PLAN
+    PLAN -->|动态分组讨论| PAR{"design-swarm"}
+    PAR --> AR2["architect"]
+    PAR --> UX2["ui-ux-designer"]
+    PAR --> FE2["frontend-engineer"]
+    PAR --> BE2["backend-engineer"]
+    AR2 --> DRB2["Design Review Board"]
+    UX2 --> DRB2
+    FE2 --> DRB2
+    BE2 --> DRB2
+    DRB2 --> HH["/handoff<br/>handoff-ready"]
+
+    HH --> EXEC["/team-execute"]
+    EXEC -->|"upstream_challenge<br/>质疑方案"| EXEC
+    EXEC -->|构建失败| BER2["build-error-resolver"]
+    BER2 --> EXEC
+    EXEC -->|代码完成| CRB["Code Review Board"]
+    CRB -->|安全问题| SR2["security-reviewer"]
+    SR2 --> CRB
+    CRB --> EXEC
+
+    EXEC --> REVIEW["/team-review<br/>qa-engineer"]
+    REVIEW -->|"upstream_challenge<br/>质疑自测充分性"| REVIEW
+    REVIEW -->|Bug 打回| EXEC
+    REVIEW -->|放行| RELEASE["/team-release<br/>devops-engineer"]
+
+    RELEASE -->|"upstream_challenge<br/>质疑发布可行性"| RELEASE
+    RELEASE --> CLOSE["tech-lead 收口"]
+```
+
+---
+
+## 2. Handoff 矩阵表
+
+### 2.1 Role → Role 交接
+
+| 发送方 | 接收方 | 触发条件 | 必须传递的产物 | 接收方质量门禁 | 常见失败模式 |
+|--------|--------|----------|---------------|---------------|-------------|
+| `product-manager` | `tech-lead` | PRD 完成 | PRD、用户故事、验收标准、UI/UX 约束摘要 | PRD 有明确的 In/Out Scope 和可测验收标准 | PRD 太模糊，缺少反例分析 |
+| `tech-lead` | `architect` | /team-plan 进入 design-swarm | 需求简报、约束、设计方向 | 输入有明确的业务边界和技术约束 | 约束不完整导致方案偏离 |
+| `tech-lead` | `ui-ux-designer` | /team-plan 进入 design-swarm（涉及 UI） | PRD、产品类型、目标端、关键页面意图 | PRD 包含 UI 方向说明 | 缺少产品类型和信息密度说明 |
+| `tech-lead` | `frontend-engineer` | /team-plan 进入 design-swarm 或 /team-execute | 架构方案、UI/UX Design Spec、设计 token | Design Spec 已通过 Review Board | 设计与架构不对齐 |
+| `tech-lead` | `backend-engineer` | /team-plan 进入 design-swarm 或 /team-execute | 架构方案、接口契约、数据模型 | 接口契约有完整的请求/响应/错误定义 | 接口契约不完整或版本冲突 |
+| `tech-lead` | `project-manager` | PRD 完成 | PRD、技术约束、资源信息 | 有可排期的任务粒度 | 任务粒度太粗无法排期 |
+| `tech-lead` | `qa-engineer` | /team-execute 完成 | PRD、Execute Log、前后端自测结果 | 有可验证的验收标准和自测证据 | 自测不充分，缺少边界态 |
+| `tech-lead` | `devops-engineer` | /team-review 放行 | 放行建议、变更清单、配置差异 | 放行建议无阻塞项 | 环境配置遗漏 |
+| `architect` | `tech-lead` | 架构设计完成 | ADR、组件拆分、接口约定、风险清单 | 方案可执行且风险已标注 | 过度设计或风险被低估 |
+| `ui-ux-designer` | `tech-lead` | Design Spec 完成 | UI/UX Design Spec、设计 token 决策、体验风险清单 | Spec 包含状态定义和响应式策略 | 缺少异常态和边界态设计 |
+| `frontend-engineer` | `qa-engineer` | 前端实现完成 | 代码变更、自测结果、UI Review Checklist | 四态（loading/empty/error/success）完整 | 只有成功态，缺少异常态 |
+| `backend-engineer` | `qa-engineer` | 后端实现完成 | 代码变更、自测结果、接口实际行为 | 接口契约和实际行为一致 | 接口行为与契约漂移 |
+| `qa-engineer` | `tech-lead` | 测试完成 | 测试计划、执行结果、放行建议 | 核心路径全部通过 | 边界态覆盖不足 |
+| `qa-engineer` | `frontend-engineer` | Bug 打回 | Bug 描述、复现步骤、期望行为 | Bug 可复现且有明确预期 | Bug 描述模糊 |
+| `qa-engineer` | `backend-engineer` | Bug 打回 | Bug 描述、复现步骤、期望行为 | Bug 可复现且有明确预期 | Bug 描述模糊 |
+| `devops-engineer` | `tech-lead` | 发布完成 | 发布结果、监控状态、异常项 | 发布成功且监控正常 | 发布后监控缺失 |
+
+### 2.2 Role → Specialist 调用
+
+| 发送方（Role） | 接收方（Specialist） | 触发条件 | 必须传递的产物 | 结论回落 |
+|----------------|---------------------|----------|---------------|---------|
+| `tech-lead` | `planner` | 复杂需求拆解 | 需求背景、约束 | 回落到 /team-plan 输出 |
+| `tech-lead` | `harness-optimizer` | 平台审计 | 当前配置 | 回落到 docs/memory/ |
+| `backend-engineer` | `code-reviewer` | 代码完成 | 代码变更 diff | 回落到 Execute Log |
+| `backend-engineer` | `build-error-resolver` | 构建失败 | 错误日志 | 回落到 /team-execute |
+| `backend-engineer` | `java-build-resolver` | Java 构建失败 | 错误日志 | 回落到 /team-execute |
+| `frontend-engineer` | `code-reviewer` | 代码完成 | 代码变更 diff | 回落到 Execute Log |
+| `frontend-engineer` | `build-error-resolver` | 构建失败 | 错误日志 | 回落到 /team-execute |
+| `qa-engineer` | `tdd-guide` | 测试策略制定 | PRD、代码结构 | 回落到 Test Plan |
+| `qa-engineer` | `e2e-runner` | E2E 测试执行 | 测试场景 | 回落到 /team-review |
+| `qa-engineer` | `security-reviewer` | 安全相关变更 | 代码变更 | 回落到 /team-review |
+| `devops-engineer` | `chief-of-staff` | 跨角色同步 | 发布状态 | 回落到 /team-release |
+
+### 2.3 Specialist → Specialist 级联
+
+| 发送方 | 接收方 | 触发条件 | 常见失败模式 |
+|--------|--------|----------|-------------|
+| `code-reviewer` | `security-reviewer` | 代码评审中发现安全风险 | 安全问题被标记为"低优先级"跳过 |
+| `code-reviewer` | `performance-optimizer` | 评审中发现性能瓶颈 | 性能问题延后处理后被遗忘 |
+| `build-error-resolver` | 语言专项 resolver | 通用 resolver 无法定位语言特有问题 | 错误选择了 resolver 类型 |
+| `planner` | `architect` | 规划中发现架构决策点 | 架构决策未同步回 Role Agent |
+| `tdd-guide` | `e2e-runner` | 单元测试后需要 E2E 验证 | E2E 环境不可用 |
+
+---
+
+## 3. Upstream Challenge（反向推理）交接规则
+
+每次 handoff 的接收方必须执行 `upstream_challenge` 协议，并把它视为阶段切换前置条件：
+
+1. **接收方阅读**上游产出后，必须对至少 1 个输入提出质疑
+2. **质疑记录**追加到 handoff 文档的「下游质疑记录」字段（[handoff-contract.md](../../rules/handoff-contract.md) 第 12 项）
+3. **质疑结论**为以下三种之一：`接受原方案` / `要求上游修改` / `升级给 tech-lead`
+4. **门禁**：未完成质疑记录的 handoff 视为不合格交接
+5. **阶段门禁**：未达到 `handoff-ready` 的 handoff 不得触发 `/team-execute`
+
+各角色的质疑维度定义在 `roles/*/role.yaml` 的 `upstream_challenge` 字段中，具体包含：
+- `trigger`：何时触发质疑
+- `mandatory_questions`：必须质疑的问题列表
+- `output`：质疑记录的标准输出
+- `gate`：未完成质疑时的阻断规则
+
+---
+
+## 4. 质量门禁总览
+
+| 检查点 | 门禁内容 | 未通过的处理 |
+|--------|---------|-------------|
+| Handoff 交接 | 接收方完成 upstream_challenge，质疑记录不为空，且状态可达 `handoff-ready` | 打回，要求补充 |
+| Design Review Board | 四方设计对齐，无阻塞冲突 | 打回冲突方，tech-lead 仲裁 |
+| Code Review Board | 无 CRITICAL/HIGH 问题 | 打回实现角色 |
+| Security Review | 无 CRITICAL 安全漏洞 | 阻断发布流程 |
+| QA 放行 | 核心路径通过，无阻塞 Bug | 打回实现角色或升级 tech-lead |
+| Release Gate | 回滚方案可行，监控覆盖 | 推迟发布 |
+
+---
+
+## 5. 失败模式与防范
+
+| 失败模式 | 表现 | 防范措施 |
+|---------|------|---------|
+| 空气交接 | 只说"我做完了"，没有结构化产物 | handoff-contract.md 强制字段校验 |
+| 质疑缺失 | 接收方未挑战上游输入就开始工作 | upstream_challenge gate 阻断 |
+| Specialist 脱轨 | specialist 结论未回落到 role agent | agent-governance.md 约束 |
+| 并行冲突 | 并行 agent 写同一文件 | file ownership locking |
+| 升级黑洞 | 问题升级给 tech-lead 后无回应 | 升级必须有超时和备选方案 |
+| Bug 打回循环 | Bug 在 QA 和开发间反复打回 | 第 3 次打回升级到 tech-lead |

package/docs/runbooks/helm-unittest-playbook.md

@@ -0,0 +1,101 @@
+# Helm Unittest 门禁手册
+
+本手册承接 `helm-unittest/helm-unittest` 的工程实践，用于把 Helm chart 的单元测试接入 PR、评审和发布前预检。它补的是“模板渲染后的 chart 片段是否符合预期”这一层，强调本地渲染、纯 YAML 测试和快照断言，不负责替代 Kubernetes schema、policy 或集群级验证。
+
+## 用途/定位
+
+`helm-unittest` 是 Helm chart 的单元测试插件，定位是用可重复执行的测试把 chart 的设计意图固化下来。它适合验证模板输出、values 组合、release 选项、局部结构和 snapshot 稳定性，重点解决的是“chart 改了之后，渲染结果是不是还是我们要的样子”。
+
+它更像 chart 层的行为测试，而不是集群层的接收性验证。换句话说，它回答的是“模板输出是否符合预期”，不是“这个对象是否已经被 Kubernetes 接受”。
+
+## 适用场景
+
+- chart 模板逻辑复杂，分支多，容易因 values 或条件渲染回归。
+- 需要对某个 template、模板片段或 subchart 默认值做精确断言。
+- 希望在不触碰集群的情况下验证渲染结果、快照和局部结构。
+- 需要把容易变化但又必须稳定的输出用 snapshot 锁定，减少人工目检。
+- 团队希望对 YAML test suite 做 schema completion 和 validation，降低测试文件编写成本。
+
+## 不适用场景
+
+- 期待它验证最终 manifest 是否满足 Kubernetes OpenAPI schema。
+- 期待它做集群 admission、server-side 语义校验或真正 apply 行为的替身。
+- 期待它表达组织级安全、合规、网络隔离、镜像来源或权限控制策略。
+- 期望它替代 `kubectl-server-dry-run-gates` 这类面向 API server 的接收性预检。
+- 只有纯 YAML 格式 lint 需求，没有 chart 渲染行为断言需求。
+
+## 推荐落地方式
+
+1. 把 `helm-unittest` 放在 chart 开发和 PR 验证的前段，先用单元测试锁定渲染意图，再交给后续结构和策略门禁。
+2. 先覆盖高价值模板：
+   - 条件分支多的 template
+   - 容易回归的 labels、annotations、env、resources、probe、volume、service 端口
+   - subchart 默认值和 alias 场景
+3. 用纯 YAML 编写测试套件，并对关键场景保留 snapshot；变更时通过显式更新快照确认意图。
+4. 在 repo 里把 chart 单测与后续门禁分层：
+   - `helm-unittest` 负责 chart 模板的本地渲染断言和 snapshot
+   - `kubeconform-schema-gates` 负责渲染后 manifest 的 schema 级结构校验
+   - `conftest-policy-gates` 负责结构化配置上的 policy-as-code
+   - `kubectl-server-dry-run-gates` 负责把变更送到 API server 做不落盘预检
+5. 如果一个问题需要知道“渲染出来像不像预期”，先用 `helm-unittest`；如果需要知道“这个对象能不能被 Kubernetes 接受”，交给后续门禁。
+6. 结果应回写到 `/team-review`、`/team-release` 或 chart 维护文档，不要只停在本地测试输出。
+
+## 边界说明
+
+- 与 `kubeconform-schema-gates` 的边界：`helm-unittest` 看的是 chart 模板和快照，`kubeconform` 看的是渲染后的 manifest 是否符合 schema。
+- 与 `conftest-policy-gates` 的边界：`helm-unittest` 验证 chart 输出是否符合设计，`conftest` 验证结构化配置是否符合 policy。
+- 与 `kubectl-server-dry-run-gates` 的边界：`helm-unittest` 是纯本地测试，不访问集群；`kubectl --dry-run=server` 是把对象送到 API server 做不落盘预检。
+
+## 最小门禁模型
+
+- `input layer`：chart templates、values、release options、subchart inputs
+- `render layer`：`helm-unittest` 本地渲染
+- `assertion layer`：YAML assertions、document selector、wildcard template selection、snapshot 比对
+- `decision layer`：chart owner、`qa-engineer`、`devops-engineer`、`tech-lead` 根据结果判断是否阻塞合并或发布
+
+最小模型的关键，不是“命令有没有跑完”，而是团队是否能稳定回答：
+
+- 这个对象是因为 chart 逻辑问题失败，还是因为 snapshot 已经过期
+- 失败来自 template 分支、values 组合、subchart 作用域，还是测试写法本身
+- 这次 `helm-unittest` 的结果能否代表 chart 渲染意图，还是还必须交给后续 schema / policy / server-side 门禁继续判断
+
+## 重点检查项
+
+- 是否覆盖了真正容易回归的模板，而不是只挑几个 happy path。
+- 是否明确了 values 覆盖、release 选项和 subchart 作用域，避免测试通过但实际渲染不一致。
+- snapshot 是否只用于稳定输出，避免把高度不稳定的内容也锁进基线。
+- 是否能区分“预期内的快照更新”和“模板行为变化导致的意外漂移”。
+- 是否对模板选择范围足够明确，避免因 wildcard 过宽而漏测或误测。
+- 是否把失败结果写成可行动信息，而不是只保留一段本地测试日志。
+- 是否已经把 chart 层问题和 manifest 层问题分开，避免把 `helm-unittest` 当成全能门禁。
+
+## 反模式
+
+- 把所有模板都做成 snapshot，最后快照只会制造噪音。
+- 只依赖 `helm-unittest`，完全跳过 schema、policy 和 server-side 预检。
+- 把集群相关、环境相关或权限相关的行为硬塞进本地 chart 单测。
+- 频繁无审核地更新 snapshot，导致测试失去约束力。
+- 把失败一律解释成“测试不稳定”，不回头检查 chart 逻辑或测试设计。
+
+## 输出回落
+
+- PR 阶段：把模板回归、snapshot 漂移、测试覆盖缺口和建议修正写入 review 摘要。
+- 评审阶段：在 `/team-review` 中明确这是 chart 层单测结果，并标注是否还需要 schema、policy 或 server-side 门禁继续判断。
+- 发布阶段：若 chart 变更仍存在高风险回归，必须回写到 `/team-release` 的阻塞项、风险项或修复待办中。
+- 治理阶段：把稳定的测试模式、snapshot 更新约定和 chart owner 责任沉淀到团队 runbook。
+
+## 许可证与使用边界
+
+- `helm-unittest/helm-unittest` 采用 MIT license。
+- `helm-unittest` 是 Helm plugin，可通过 `helm` CLI 使用，也可以通过容器化方式运行；它属于 Helm 的插件扩展，而不是 Helm core。
+- 它只验证 chart 的本地渲染结果，不负责创建资源，也不替代 API server 的接收性验证。
+- 它适合做 chart 层的回归测试，不适合单独作为发布放行的最终证明。
+
+## 参考来源
+
+- [helm-unittest/helm-unittest](https://github.com/helm-unittest/helm-unittest)
+- [The Helm Plugins Guide](https://helm.sh/docs/topics/plugins/)
+- [kubectl apply | Kubernetes](https://kubernetes.io/docs/reference/kubectl/generated/kubectl_apply)
+- [kubeconform-schema-gates.md](kubeconform-schema-gates.md)
+- [conftest-policy-gates.md](conftest-policy-gates.md)
+- [kubectl-server-dry-run-gates.md](kubectl-server-dry-run-gates.md)

package/docs/runbooks/hotfix-emergency-release-walkthrough.md

@@ -0,0 +1,60 @@
+---
+version: "0.1.0"
+status: draft
+created: 2026-03-28
+updated: 2026-03-28
+owner: 工程团队
+---
+
+# 紧急修复发布演练
+
+本文演示紧急问题如何快速判断、修复、验证和发布。重点是快，但不能把结构化验证和回滚准备全部省掉。
+
+## 1. 场景
+
+- 线上 bug 影响关键流程
+- 需要快速修复并发布
+- 同时要保留最基本的 review、验证和回滚准备
+
+## 2. 推荐链路
+
+1. `/team-intake`
+2. `/team-execute`
+3. `/code-review`
+4. `/verify`
+5. `/team-release`
+
+是否进入完整 `/team-plan`，由问题复杂度决定。
+
+## 3. intake 阶段的判断重点
+
+- 影响范围
+- 是否为真正 hotfix
+- 是否需要回滚优先于修复
+
+## 4. execute 阶段的要求
+
+- 修复范围最小化
+- 自测覆盖关键路径
+- 记录回归风险
+
+## 5. verify 阶段的要求
+
+- 验证关键用户路径
+- 验证是否引入新问题
+- 明确观察指标
+
+## 6. release 阶段的要求
+
+- 上线步骤
+- 回滚条件
+- 观察窗口
+- 监控指标
+
+## 7. 常见错误
+
+- 紧急修复就完全跳过 review
+- 没有观察窗口和回滚条件
+- 问题修复后没有复盘
+
+与排障和 release 相关说明配合阅读：[troubleshooting.md](troubleshooting.md)

package/docs/runbooks/iac-kubernetes-platform-demo-execution-log.md

@@ -0,0 +1,144 @@
+---
+version: "0.1.0"
+status: draft
+created: 2026-03-29
+updated: 2026-03-29
+owner: 工程团队
+---
+
+# IaC 与 Kubernetes 平台演示执行记录
+
+本文记录一条 IaC / Kubernetes 平台演示路径，重点展示团队如何把 chart、schema、policy、server-side 预检和发布收口串成可解释的治理链路。
+
+## 1. 场景定义
+
+### 背景
+
+- 仓库当前主要维护 Helm Chart、manifest、policy 与环境发布配置
+- 过去门禁零散存在，但缺少统一的分层说明和 release 收口
+- 团队希望把 IaC 变更从“能跑”升级成“可验证、可回滚、可复盘”
+
+### 演示目标
+
+- 让观众理解四层验证边界
+- 让观众看到 `/tdd` 如何前置定义完成标准
+- 让观众看到 `/verify` 如何把零散结果汇总成正式结论
+
+## 2. 阶段 1：/team-intake
+
+### 输入
+
+```text
+/team-intake
+目标：补齐 Kubernetes 平台仓库的 chart、schema、policy 和发布门禁
+范围：Helm Chart、manifest、policy、验证脚本、release 说明
+不做：业务服务逻辑改造
+约束：必须区分 helm unittest、kubeconform、conftest/kyverno 和 server-side dry-run 的边界
+```
+
+### 产出
+
+| 字段 | 内容 |
+|------|------|
+| 任务类型 | IaC / 平台治理 |
+| 主体对象 | chart、manifest、policy、release 基线 |
+| 主要风险 | 环境范围不清、验证层混淆、回滚路径缺失 |
+| 收口要求 | review 与 release 必须承接分层验证结论 |
+
+## 3. 阶段 2：/team-plan
+
+### 拆解结果
+
+| 模块 | 动作 | 收口位置 |
+|------|------|----------|
+| Chart 层 | 调整模板与 values | chart |
+| Schema 层 | 校验渲染后 manifest 结构 | CI / verify |
+| Policy 层 | 校验组织级规则 | CI / review |
+| Server-side | 做 API server 预检 | verify / release |
+| 发布层 | 记录环境范围与回滚方式 | release |
+
+### 关键判断
+
+- `helm-unittest` 解决 chart 渲染意图
+- `kubeconform` 解决 manifest schema
+- `conftest/kyverno` 解决 policy
+- `kubectl --dry-run=server` 解决接收性预检
+
+## 4. 阶段 3：/tdd
+
+### 定义的完成标准
+
+```text
+1. chart、schema、policy、server-side 四层验证边界明确
+2. verify 能汇总四层结果
+3. review 结论能记录阻塞项与例外
+4. release 记录能说明环境范围与回滚方式
+5. 仓库校验通过
+```
+
+## 5. 阶段 4：/team-execute
+
+### 执行批次
+
+#### 批次 A：chart 与 values
+
+- 调整模板逻辑
+- 补 chart 单测或快照
+
+#### 批次 B：schema 与 policy
+
+- 补 schema 校验
+- 补 policy 校验与例外说明
+
+#### 批次 C：server-side 与发布
+
+- 补 server-side 预检
+- 更新 release 与回滚记录
+
+## 6. 阶段 5：/verify
+
+### Verify 结果
+
+| 检查项 | 判断 |
+|--------|------|
+| Chart 渲染 | 已确认 |
+| Schema 校验 | 已确认 |
+| Policy 校验 | 已确认 |
+| Server-side 预检 | 已确认 |
+| 发布收口 | 已确认 |
+
+## 7. 阶段 6：/team-review 与 /team-release
+
+### Review 结论
+
+- 当前阻塞项已按分层验证归类
+- 例外项有明确解释，不再混入统一结论
+
+### Release 结论
+
+- 发布记录明确环境范围、依赖条件和回滚方式
+- 一旦异常，可快速定位是 chart、policy 还是发布预检问题
+
+## 8. 校验结果
+
+### 文档静态检查
+
+- 本轮新增 walkthrough、demo script 与 execution log 无错误
+
+### 仓库校验
+
+```text
+Validation passed.
+- Roles: 8
+- Shared skills: 3
+- ECC skills: 9
+- Private overlay skills: not shipped in public repo
+- Specialist agents: 27
+- Generated artifacts: 70
+```
+
+## 9. 推荐搭配材料
+
+- [iac-kubernetes-platform-demo-script.md](iac-kubernetes-platform-demo-script.md)
+- [iac-kubernetes-platform-walkthrough.md](iac-kubernetes-platform-walkthrough.md)
+- [../../examples/iac-kubernetes-platform-CLAUDE.md](../../examples/iac-kubernetes-platform-CLAUDE.md)

package/docs/runbooks/iac-kubernetes-platform-demo-script.md

@@ -0,0 +1,130 @@
+---
+version: "0.1.0"
+status: draft
+created: 2026-03-29
+updated: 2026-03-29
+owner: 工程团队
+---
+
+# IaC 与 Kubernetes 平台演示剧本
+
+本文是一份可直接照着讲的演示脚本，面向 Helm Chart、Kubernetes manifest、policy、schema 校验和发布前预检场景。
+
+## 1. 演示目标
+
+- 说明 chart、schema、policy、server-side dry-run 是四层不同验证问题
+- 说明 `/tdd` 如何前置定义分层验证完成标准
+- 说明 `/verify` 如何把零散门禁结果收敛成 review / release 可用结论
+
+## 2. 适用对象
+
+- 需要介绍 IaC 治理能力的 Tech Lead
+- 需要做发布门禁说明的 DevOps / QA
+- 需要解释 Helm / Kubernetes 分层验证边界的讲解人
+
+## 3. 演示时长建议
+
+- 5 分钟：讲四层验证边界
+- 10 分钟：再讲 `/tdd` 与 `/verify`
+- 15 分钟：完整走一遍 intake -> plan -> tdd -> execute -> verify -> review/release
+
+## 4. 演示脚本
+
+### Step 1. 先用 1 分钟讲清 IaC 任务在治理什么
+
+建议讲法：
+
+```text
+IaC 平台仓库要治理的不是一条命令，而是四层验证：
+第一层是 chart 渲染意图；
+第二层是 manifest schema；
+第三层是 policy 约束；
+第四层是 API server 接收性预检。
+```
+
+配套材料：
+
+- [helm-unittest-playbook.md](helm-unittest-playbook.md)
+- [kubeconform-schema-gates.md](kubeconform-schema-gates.md)
+- [conftest-policy-gates.md](conftest-policy-gates.md)
+- [kubectl-server-dry-run-gates.md](kubectl-server-dry-run-gates.md)
+
+### Step 2. 用 `/team-intake` 讲清目标和边界
+
+建议输入：
+
+```text
+/team-intake
+目标：补齐 Kubernetes 平台仓库的 chart、schema、policy 和发布门禁
+范围：Helm Chart、manifest、policy、验证脚本、release 说明
+不做：业务服务逻辑改造
+约束：必须区分 helm unittest、kubeconform、conftest/kyverno 和 server-side dry-run 的边界
+```
+
+讲解重点：
+
+- 这是 IaC 平台治理任务，不是普通后端任务
+- 一开始就要把四层验证拆开，否则结论会失真
+
+### Step 3. 用 `/team-plan` 说明如何拆分层验证任务
+
+建议输入：
+
+```text
+/team-plan
+基于当前 intake 结果，拆 chart 变更、schema 校验、policy 校验、server-side 预检和 release 收口动作。
+输出必须指出哪些完成标准应先进入 /tdd，哪些证据最终应由 /verify 汇总。
+```
+
+### Step 4. 用 `/tdd` 讲“先锁验证分层标准”
+
+建议输入：
+
+```text
+/tdd
+基于当前 /team-plan 结果，先定义本轮 IaC 变更的完成标准。
+至少覆盖：
+1. chart 渲染意图有验证
+2. manifest schema 校验通过
+3. policy 结果可解释
+4. server-side 预检结果能进入 release 结论
+```
+
+### Step 5. 用 `/team-execute` 讲实际收敛动作
+
+建议讲法：
+
+```text
+执行阶段通常会先调 chart 和 values，再补 schema 与 policy 门禁，最后补 server-side 预检和 release 说明。
+```
+
+### Step 6. 用 `/verify` 收口
+
+建议输入：
+
+```text
+/verify
+请基于当前 IaC 变更，输出 chart 渲染、schema、policy、server-side 预检结果、环境风险和可直接进入 /team-review 或 /team-release 的结论。
+```
+
+### Step 7. 用 review 与 release 收尾
+
+建议讲法：
+
+```text
+最终交付不是“CI 通过了”，而是 review 能解释阻塞项，release 能解释环境范围、回滚路径和剩余风险。
+```
+
+## 5. 建议演示顺序
+
+1. 先讲 chart / schema / policy / dry-run 四层边界
+2. 再展示 `/team-intake` 与 `/team-plan`
+3. 然后讲 `/tdd`
+4. 再讲 `/team-execute`
+5. 最后讲 `/verify`、`/team-review` 和 `/team-release`
+
+## 6. 演示后建议发给观众的材料
+
+- [iac-kubernetes-platform-demo-execution-log.md](iac-kubernetes-platform-demo-execution-log.md)
+- [iac-kubernetes-platform-walkthrough.md](iac-kubernetes-platform-walkthrough.md)
+- [../../examples/iac-kubernetes-platform-CLAUDE.md](../../examples/iac-kubernetes-platform-CLAUDE.md)