@colin4k1024/tsp 2.4.1 → 2.4.2

package/docs/runbooks/plugin-extension-platform-demo-script.md

@@ -0,0 +1,102 @@
+---
+version: "0.1.0"
+status: draft
+created: 2026-03-29
+updated: 2026-03-29
+owner: 工程团队
+---
+
+# 插件与扩展平台演示剧本
+
+本文是一份可直接照着讲的演示脚本，面向宿主集成点、命令入口、配置面、安装路径和兼容矩阵场景。
+
+## 1. 演示目标
+
+- 说明插件仓库为什么要同时治理命令面、配置面和安装路径
+- 说明 `/tdd` 如何前置锁定兼容和升级完成标准
+- 说明 `/verify` 如何收口宿主集成点、安装路径和配置验证结果
+
+## 2. 适用对象
+
+- 需要介绍插件 / 扩展交付方法的 Tech Lead
+- 需要讲宿主兼容与安装路径的前端 / 工具链负责人
+- 需要向团队解释 verify 为何必须覆盖升级和禁用态的讲解人
+
+## 3. 演示时长建议
+
+- 5 分钟：讲命令面、配置面、安装路径三类风险
+- 10 分钟：再讲 `/tdd` 与 `/verify`
+- 15 分钟：完整走一遍 intake -> plan -> tdd -> execute -> verify -> review
+
+## 4. 演示脚本
+
+### Step 1. 先用 1 分钟讲清插件任务在治理什么
+
+建议讲法：
+
+```text
+插件仓库要治理的不只是一个命令入口，至少还有配置项、宿主兼容和安装升级路径。
+如果只改功能不改这些外围入口，发布后最容易出问题。
+```
+
+### Step 2. 用 `/team-intake` 讲清任务边界
+
+建议输入：
+
+```text
+/team-intake
+目标：为插件仓库新增命令入口并补齐安装、配置与兼容性说明
+范围：命令、配置项、集成点、安装文档、测试计划
+不做：无关业务服务改造
+约束：必须说明宿主版本边界、升级路径、禁用态和失败回退行为
+```
+
+### Step 3. 用 `/team-plan` 说明如何拆分集成任务
+
+建议输入：
+
+```text
+/team-plan
+基于当前 intake 结果，拆命令入口、配置项、宿主集成、安装路径、兼容矩阵和验证收口动作。
+输出必须指出哪些完成标准应先进入 /tdd，哪些证据最终应由 /verify 汇总。
+```
+
+### Step 4. 用 `/tdd` 讲“先锁兼容与升级标准”
+
+建议输入：
+
+```text
+/tdd
+基于当前 /team-plan 结果，先定义命令入口、配置兼容、安装升级、禁用态和失败回退的完成标准。
+```
+
+### Step 5. 用 `/team-execute` 讲实际收敛动作
+
+建议讲法：
+
+```text
+执行阶段通常会先补命令入口和配置项，再补安装升级说明，最后补兼容矩阵和验证收口。
+```
+
+### Step 6. 用 `/verify` 收口
+
+建议输入：
+
+```text
+/verify
+请基于当前插件改动，输出命令入口、配置项、安装路径和兼容性验证结果，并整理成可直接进入 /team-review 的结论。
+```
+
+## 5. 建议演示顺序
+
+1. 先讲命令面、配置面、安装路径三类风险
+2. 再展示 `/team-intake` 与 `/team-plan`
+3. 然后讲 `/tdd`
+4. 再讲 `/team-execute`
+5. 最后讲 `/verify` 与 `/team-review`
+
+## 6. 演示后建议发给观众的材料
+
+- [plugin-extension-platform-demo-execution-log.md](plugin-extension-platform-demo-execution-log.md)
+- [plugin-extension-platform-walkthrough.md](plugin-extension-platform-walkthrough.md)
+- [../../examples/plugin-extension-platform-CLAUDE.md](../../examples/plugin-extension-platform-CLAUDE.md)

package/docs/runbooks/plugin-extension-platform-walkthrough.md

@@ -0,0 +1,111 @@
+---
+version: "0.1.0"
+status: draft
+created: 2026-03-29
+updated: 2026-03-29
+owner: 工程团队
+---
+
+# 插件与扩展平台演练
+
+本文演示一个以命令入口、配置项、宿主集成点和安装路径为核心的插件 / 扩展仓库，如何从需求澄清、兼容性约束到验证收口完整跑通。
+
+## 1. 场景
+
+- 仓库当前主要维护 extension / plugin、命令、配置项和安装说明
+- 团队准备新增一个宿主命令入口，并同步补齐配置、兼容矩阵和安装路径
+- 目标不是开发独立业务功能，而是把扩展点和安装链路治理成可验证、可发布、可回退的状态
+
+## 2. 推荐链路
+
+1. `/team-intake`
+2. `/team-plan`
+3. `/tdd`
+4. `/team-execute`
+5. `/verify`
+6. `/team-review`
+
+## 3. 第一步：/team-intake
+
+### 输入示例
+
+```text
+/team-intake
+目标：为插件仓库新增命令入口并补齐安装、配置与兼容性说明
+范围：命令、配置项、集成点、安装文档、测试计划
+不做：无关业务服务改造
+约束：必须说明宿主版本边界、升级路径、禁用态和失败回退行为
+```
+
+### 期望输出重点
+
+- 识别这是插件 / 扩展交付任务，而不是普通应用开发
+- 明确参与角色至少包括 `tech-lead`、`architect`、`qa-engineer`
+- 风险应聚焦宿主边界不清、命令入口失联、配置升级不兼容和安装回退不明确
+
+## 4. 第二步：/team-plan
+
+### 需要拆清的动作
+
+- 命令入口与贡献点调整
+- 配置项、默认值与升级兼容策略
+- 安装路径、启用 / 禁用路径和失败回退
+- 宿主版本矩阵与验证范围
+- review 中需要记录的兼容性与发布说明
+
+### 合格输出应该回答
+
+1. 哪些改动影响命令面
+2. 哪些影响配置面
+3. 哪些影响安装与升级路径
+4. 哪些兼容风险需要 verify 覆盖
+
+## 5. 第三步：/tdd
+
+在这类仓库里，`/tdd` 重点是先锁安装与兼容完成标准：
+
+- 命令入口与配置边界是否说清
+- 最低宿主版本与升级路径是否明确
+- 禁用态、失败态和回退路径是否可验证
+- 哪些验证证据必须进入 review
+
+## 6. 第四步：/team-execute
+
+执行阶段通常包含：
+
+- 调整命令入口或宿主集成点
+- 调整配置项、默认值和兼容处理
+- 更新安装说明、升级说明与故障回退说明
+- 补关键验证用例和测试计划
+
+本阶段输出至少应包含：
+
+- 集成点变更摘要
+- 配置与兼容变更摘要
+- 安装 / 升级验证结果
+- 剩余风险和例外项
+
+## 7. 第五步：/verify
+
+Verify 阶段要回答：
+
+- 命令入口是否可用
+- 配置项和默认值是否兼容既有安装
+- 安装、升级和禁用路径是否可执行
+- 宿主版本矩阵是否覆盖关键场景
+
+## 8. 第六步：/team-review
+
+Review 阶段要回答：
+
+- 当前是否还存在阻塞发布的兼容问题
+- 哪些例外可以暂时接受
+- 是否需要补更多宿主版本或安装路径验证
+
+## 9. 常见错误
+
+- 只改命令入口，不更新安装和配置说明
+- 只验证 happy path，不验证禁用态和升级路径
+- 宿主兼容矩阵说得很笼统，无法指导 QA
+
+建议配合阅读：[codex-workflow-essentials.md](codex-workflow-essentials.md)、[troubleshooting.md](troubleshooting.md)、[project-onboarding.md](project-onboarding.md)

package/docs/runbooks/policy-controller-gates.md

@@ -0,0 +1,75 @@
+# Policy Controller 策略强制门禁手册
+
+本手册承接 `sigstore/policy-controller` 的工程实践，用于把 Kubernetes admission 层的策略强制执行接入供应链治理链。它补的是“在集群里真正拦住不符合策略的镜像和工作负载”这一层，不替代 SBOM、签名、provenance attestation、SLSA verification 或漏洞扫描。
+
+## 适用场景
+
+- 团队已经有 `cosign`、provenance attestation 或 SLSA verification，想把“建议验证”推进到“集群 admission 强制执行”。
+- 需要在 Kubernetes 集群内按 namespace 或工作负载范围强制要求镜像签名、attestation 或其他可验证的供应链元数据。
+- 仓库的镜像来源复杂，单靠 CI / release 流程不足以保证运行中的 workload 没有被替换或绕过治理。
+
+## 不适用场景
+
+- 当前还没有稳定的签名、attestation 或验证链，却先上 admission 强制，导致拦截全靠猜。
+- 团队还没有明确哪些 namespace、workload 或镜像类型需要受策略约束。
+- 期望 policy controller 替代 CI 侧的 SBOM、签名、验证和人工放行流程。
+
+## 推荐落地方式
+
+1. 先把策略范围收窄到少数关键 namespace，不要一开始全集群拦截。
+2. 第一阶段先固定三件事：
+   - 哪些 workload 或 namespace 受策略约束
+   - 策略依据是什么，例如签名、attestation 或仓库来源
+   - 拒绝时如何回退、告警和 triage
+3. 将 policy controller 与现有链路分层：
+   - `sbom-generation-gates` 负责成分清单
+   - `artifact-attestation-gates` 负责 provenance 证明
+   - `cosign-signing-gates` 负责签名与验签
+   - `slsa-verification-gates` 负责独立验证 provenance / attestation
+   - `kyverno-policy-gates` 负责更通用的 Kubernetes admission、background scan 和 policy report 治理
+   - policy controller 负责在 admission 层强制执行这些可验证策略
+4. 建议先从“观察模式”或“单 namespace 强制”开始，再逐步扩大范围。
+5. 结果必须回写到 `/team-release`、集群治理记录或运行手册，不让策略结果只停在 webhook 日志里。
+
+## 最小门禁模型
+
+- `policy layer`：定义哪些 namespace、workload、镜像或来源受约束
+- `evidence layer`：签名、attestation、验证结果和镜像来源
+- `admission layer`：Kubernetes webhook 在创建或更新时执行拦截
+- `decision layer`：`devops-engineer`、`tech-lead` 决定是否把拒绝结果视为阻塞或降级
+
+重点不是“装了一个 webhook”，而是让集群真正按供应链证据执行策略。
+
+## 重点检查项
+
+- 策略是否按 namespace 或工作负载边界配置，而不是一刀切全局生效
+- 策略依据是否和镜像签名、attestation 或验证结果稳定关联
+- 镜像 tag 是否会在 admission 时被解析成 digest，避免“通过时和运行时不是同一个镜像”
+- 策略失败时是否有明确的告警、triage 和例外流程
+- 多 key、多个 policy 或不同环境之间的配置是否能持续维护
+
+## 反模式
+
+- 没有前置验证链，却先上 admission 强制，把所有问题都变成发布阻塞。
+- 策略配置只写在集群里，发布记录和治理文档里没有回链。
+- 把 policy controller 当成安全扫描器，忽略它本质上是执行层拦截器。
+- 上线后只有“拒绝了什么”，没有“为什么拒绝、谁来处理、何时放宽”的闭环。
+
+## 输出回落
+
+- 发布阶段：把受影响的 namespace、策略范围和验证结果写入 `/team-release` 的检查结果或放行结论。
+- 集群治理：把 policy 变更、例外项和告警处理记录沉淀到治理文档或 runbook。
+- 审计阶段：若某次 workload 被拦截，必须能追溯到对应的签名、attestation 或验证证据。
+
+## 许可证与使用边界
+
+- `sigstore/policy-controller` 采用 Apache-2.0。
+- 启用前应确认 Kubernetes 版本、Webhook 部署方式、镜像仓库可访问性和团队是否有足够的治理人力。
+- 参考仓库的支持说明，`policy-controller` 近版本面向 Kubernetes 1.27 到 1.29 更稳定，旧版本需单独验证。
+
+## 参考来源
+
+- [sigstore/policy-controller](https://github.com/sigstore/policy-controller)
+- [cosign-signing-gates.md](cosign-signing-gates.md)
+- [artifact-attestation-gates.md](artifact-attestation-gates.md)
+- [slsa-verification-gates.md](slsa-verification-gates.md)

package/docs/runbooks/post-rollback-verification-checklist.md

@@ -0,0 +1,37 @@
+---
+version: "0.1.0"
+status: draft
+created: 2026-03-28
+updated: 2026-03-28
+owner: 工程团队
+---
+
+# 回滚后验证检查清单
+
+本文用于回滚完成后的快速验证，避免“服务恢复了”就直接结束。
+
+## 1. 服务状态
+
+- [ ] 关键服务已恢复可用
+- [ ] 关键页面或接口已可访问
+- [ ] 依赖服务状态正常
+
+## 2. 数据与配置
+
+- [ ] 数据一致性已抽样验证
+- [ ] 配置与开关已确认回退到目标状态
+- [ ] 新旧版本混合状态已排除
+
+## 3. 指标与观察
+
+- [ ] 错误率回落到预期区间
+- [ ] 耗时或吞吐恢复到基线
+- [ ] 用户反馈或监控告警已明显收敛
+
+## 4. 后续动作
+
+- [ ] 事故记录已更新
+- [ ] 后续修复任务已登记
+- [ ] 是否需要继续观察已明确
+
+相关长文档见：[release-rollback-recovery-walkthrough.md](release-rollback-recovery-walkthrough.md)、[production-incident-response-walkthrough.md](production-incident-response-walkthrough.md)

package/docs/runbooks/pre-release-checklist.md

@@ -0,0 +1,50 @@
+---
+version: "0.1.0"
+status: draft
+created: 2026-03-28
+updated: 2026-03-28
+owner: 工程团队
+---
+
+# 发布前检查速查清单
+
+本文用于发布前 5 到 10 分钟的最后检查，不替代完整发布方案。
+
+## 1. 环境
+
+- [ ] 目标环境与发布窗口已确认
+- [ ] 责任人、值守人与观察窗口已确认
+- [ ] 必要配置与环境变量已就绪
+
+## 2. 变更
+
+- [ ] 发布范围和版本信息已锁定
+- [ ] 高风险点已单独标记
+- [ ] 数据或配置变更已确认可回退
+
+## 3. 质量
+
+- [ ] QA 放行结论明确
+- [ ] 关键链路 smoke 范围明确
+- [ ] 残余风险已进入观察项
+
+## 4. 回滚
+
+- [ ] 回滚条件已明确
+- [ ] 回滚步骤已明确
+- [ ] 回滚负责人已明确
+
+## 5. 扩展项
+
+- [ ] 如需 GitLab manual job，已确认触发条件
+- [ ] 如需 Langfuse 追踪，已确认 trace 粒度和回写位置
+
+## 6. npm 发布补充检查（适用于 npm registry 发布）
+
+- [ ] 若使用 npm Trusted Publisher，已在 npm 包设置中正确绑定 GitHub 仓库、仓库名与 workflow 文件名（例如 `publish.yml`）
+- [ ] GitHub Actions 发布 workflow 已启用 `id-token: write`
+- [ ] `npm publish` 步骤未再注入发布用 `NODE_AUTH_TOKEN` / `NPM_TOKEN`，避免从 OIDC 回落到 token 鉴权后触发 OTP
+- [ ] 若 `npm ci` 需要访问私有依赖，仅读取阶段使用只读 token；publish 阶段保持 OIDC-only
+- [ ] 若启用 provenance，已确认当前仓库与 runner 满足 npm Trusted Publishing 的支持条件
+
+相关长文档见：[team-release-example.md](team-release-example.md)、[release-governance-reading-path.md](release-governance-reading-path.md)

package/docs/runbooks/product-manager-clarification-conversation-example.md

@@ -0,0 +1,90 @@
+---
+version: "0.1.0"
+status: draft
+created: 2026-03-28
+updated: 2026-03-28
+owner: 工程团队
+---
+
+# Product Manager 需求澄清对话样例
+
+本文给出一份偏 Product Manager 视角的成品对话样例，重点展示怎样把业务语言整理成能直接进入 `/team-intake` 的输入，而不是停留在模糊需求层。
+
+## 1. 场景
+
+- 任务：业务方提出“审批记录查询太难用，需要优化”
+- 当前输入：只有业务诉求，没有清晰范围和验收标准
+- 目标：把需求整理成可进入主链的澄清结果
+
+## 2. 用户怎么说
+
+```text
+请以 product-manager 视角整理当前需求。
+输出：业务目标、核心用户场景、In Scope、Out of Scope、验收标准、待确认事项。
+最后补一段：这些内容怎样进入 /team-intake。
+```
+
+## 3. 期望结果长什么样
+
+```text
+业务目标
+- 让运营同学能更快查询审批记录，降低人工翻找成本
+
+核心用户场景
+- 运营按订单号、审批状态、创建时间筛选审批记录
+- 运营查看空结果和异常提示时能快速判断下一步动作
+
+In Scope
+- 审批记录查询列表页
+- 后端查询接口
+- 分页、筛选、空态和错误态
+
+Out of Scope
+- 审批流程定义改造
+- 历史数据回填
+- 导出能力新增
+
+验收标准
+- 支持按订单号、状态、时间范围查询
+- 无结果时有明确空态提示
+- 无权限时有明确错误提示
+
+待确认事项
+- 是否需要兼容旧查询入口的字段顺序
+- 是否存在特定角色的权限差异
+
+进入 /team-intake 的建议
+- 目标：新增审批记录查询能力
+- 范围：列表页、查询接口、测试计划
+- 不做：流程定义改造、历史数据回填、导出新增
+- 约束：判断是否涉及权限中心或 custom overlay
+```
+
+## 4. 不合格结果通常长什么样
+
+```text
+需求是把审批记录查询做好一点。
+```
+
+这类结果的问题是：
+
+- 没有用户场景
+- 没有范围边界
+- 没有验收标准
+
+## 5. Product Manager 在对话里最容易漏什么
+
+- Out of Scope
+- 可测的验收标准
+- 待确认事项
+- 这些内容如何回落成 `/team-intake` 输入
+
+## 6. 继续推进时怎么说
+
+当澄清结果形成后，下一句通常是：
+
+```text
+请基于上面的需求澄清结果继续执行 /team-intake，输出参与角色、风险和下一步建议。
+```
+
+与这些文档配合阅读：[product-manager-daily-operations.md](product-manager-daily-operations.md)、[requirement-clarity-and-scope-walkthrough.md](requirement-clarity-and-scope-walkthrough.md)、[role-prompt-recipes.md](role-prompt-recipes.md)

package/docs/runbooks/product-manager-daily-operations.md

@@ -0,0 +1,60 @@
+---
+version: "0.1.0"
+status: draft
+created: 2026-03-28
+updated: 2026-03-28
+owner: 工程团队
+---
+
+# Product Manager 日常操作手册
+
+本文面向产品经理，说明需求澄清、PRD、范围边界和验收标准如何在 Team Skills Platform 下进入主链。
+
+如果你想先看命令面和能力映射，先读 [command-and-capability-matrix.md](command-and-capability-matrix.md)。
+
+## 1. 你的默认职责
+
+- 定义问题、目标和用户价值
+- 产出 PRD、用户故事和验收标准
+- 控制范围边界，避免需求蔓延
+- 把业务意图准确交给 tech-lead、architect 和 project-manager
+
+## 2. 开始澄清前必须确认什么
+
+- 当前问题是否真实存在且值得做
+- 用户对象、核心场景和成功指标是否明确
+- 哪些内容是本次范围外事项
+- 是否存在业务优先级冲突
+
+## 3. 需求澄清时的固定检查
+
+- 目标是否可验证
+- In Scope / Out of Scope 是否明确
+- 验收标准是否可测
+- 依赖和约束是否已记录
+- 是否需要升级到 tech-lead 做仲裁
+
+## 4. 应交付什么
+
+- PRD 或等价需求说明
+- 用户故事与验收标准
+- 范围边界说明
+- 风险和待确认事项
+
+最小字段可直接按 [artifact-standards.md](../../rules/artifact-standards.md) 中的 PRD 要求组织：背景、目标与成功标准、用户故事、范围、风险与依赖。
+
+## 5. 常用命令组合
+
+- `/team-intake`：把需求转成主链输入
+- `/team-plan`：确认角色分工和下一步交付物
+- `/tdd`：当验收标准容易争议时，提前把“可测标准”压实到执行前
+- `/handoff`：把需求背景和验收标准传给研发或 QA
+
+## 6. 常见错误
+
+- 只写功能点，不写目标和成功标准
+- 验收标准不可测
+- 明明需求高风险且验收容易歧义，却没有推动团队在实现前进入 `/tdd`
+- 范围边界含糊，导致执行中不断加需求
+
+建议与这些文档配合阅读：[requirement-clarity-and-scope-walkthrough.md](requirement-clarity-and-scope-walkthrough.md)、[project-manager-daily-operations.md](project-manager-daily-operations.md)、[role-prompt-recipes.md](role-prompt-recipes.md)、[product-manager-clarification-conversation-example.md](product-manager-clarification-conversation-example.md)

package/docs/runbooks/production-incident-response-walkthrough.md

@@ -0,0 +1,50 @@
+---
+version: "0.1.0"
+status: draft
+created: 2026-03-28
+updated: 2026-03-28
+owner: 工程团队
+---
+
+# 生产事故应急响应演练
+
+本文演示线上事故从快速分级、止血、修复到后续复盘的完整协作方式。重点是多角色协同，而不是单点修 bug。
+
+## 1. 场景
+
+- 线上告警触发，审批提交成功率突然下降
+- 影响关键路径，需要快速止血
+- 可能需要临时回滚、限流或降级
+
+## 2. 推荐链路
+
+1. `/team-intake`
+2. `/team-execute`
+3. `/verify`
+4. `/handoff`
+5. `/team-release`
+
+问题复杂时，可在中间插入 `/code-review` 或 `/plan` 做专项分析。
+
+## 3. 关键输出
+
+- 事故等级与影响范围
+- 止血方案与执行结果
+- 根因假设或已确认根因
+- 后续修复和复盘建议
+
+若需要快速形成事故简报，直接按 [artifact-standards.md](../../rules/artifact-standards.md) 中的 Incident Brief 最小字段组织：事件概览、初步判断、协作分工、后续动作。
+
+## 4. 合格结果的检查点
+
+- 有单点决策人
+- 止血动作和根治动作被区分开
+- 事故记录可供后续复盘
+
+## 5. 常见错误
+
+- 多个角色同时给最终结论
+- 先争论根因，延误止血
+- 事故结束后没有沉淀后续动作
+
+与这些文档配合阅读：[tech-lead-daily-operations.md](tech-lead-daily-operations.md)、[troubleshooting.md](troubleshooting.md)