@colin4k1024/tsp 2.4.0 → 2.4.2

package/docs/runbooks/api-breaking-change-gates.md

@@ -0,0 +1,58 @@
+# API Breaking Change 门禁手册
+
+本手册承接 `OpenAPITools/openapi-diff` 的工程实践，用于把 OpenAPI 契约变更从“人工肉眼比对”升级为可执行的 breaking change 检查。它是 API 契约治理和发布前验证的补充，不替代 `api-contract` 或 `/team-review` 的人工判断。
+
+## 适用场景
+
+- 接口契约以 OpenAPI 形式维护，且需要评估本次变更是否破坏向后兼容。
+- 发布前需要明确区分 `breaking / non-breaking / unclassified` 风险。
+- 多团队共享 API，不能只靠 reviewer 凭记忆判断兼容性。
+
+## 不适用场景
+
+- 当前接口尚未形成可比对的 OpenAPI 基线文件。
+- 变更只停留在实现层，没有对外契约变化。
+- 团队没有清晰的版本或兼容性策略，diff 结果即使出来也没人负责解释。
+
+## 推荐落地方式
+
+1. 先锁定比较对象：`baseline spec` 与 `candidate spec`，不要拿不完整或不同环境生成的产物直接互比。
+2. 在做 diff 前，优先用 [api-lint-gates.md](api-lint-gates.md) 确认 spec 本身结构稳定；否则 diff 容易混入低质量文档噪音。
+3. 在方案或实现阶段先做一次预比对，尽早发现潜在 breaking change，不要等到发布前才第一次看结果。
+4. 对 diff 结果分类处理：
+   - 明确 breaking：必须改设计、升版本、做兼容层，或由 `tech-lead` 显式接受风险
+   - 明确非 breaking：记录结论，继续后续测试和发布
+   - 无法自动判断：回到 `architect` / `backend-engineer` 做人工契约评审
+5. 把 diff 结论回写到 `API Contract`、`/team-review` 或 `/team-release`，不要让结果停留在 CI 日志里。
+
+## 最小门禁模型
+
+- `input layer`：稳定的基线 OpenAPI 文件 + 当前候选 OpenAPI 文件
+- `diff layer`：生成 breaking / changed / compatible 结果
+- `decision layer`：`architect`、`backend-engineer`、`qa-engineer`、`tech-lead` 判断是否阻塞
+
+这三层必须分开：工具给出“发现”，团队给出“结论”。
+
+## 重点检查项
+
+- 删除 path、operation、response field、enum 值或 required 字段
+- 修改字段类型、约束、状态码语义或鉴权要求
+- 新增字段但改变默认行为、分页语义或错误处理方式
+- 文档中写着兼容，结果 diff 却显示 breaking
+
+## 反模式
+
+- 用实现代码或接口联调结果替代契约 diff。
+- 基线文件不稳定，却把 diff 结果当正式阻塞门禁。
+- 工具报告 breaking，团队却不做任何版本/兼容性说明。
+- 只看“有无 diff”，不解释 diff 为什么重要、影响哪些调用方。
+
+## 输出回落
+
+- 设计阶段：把兼容性结论回写到 [api-contract.md](../../templates/api-contract.md) 的兼容性部分。
+- 评审阶段：在 `/team-review` 中记录 breaking change 是否阻塞、影响哪些调用方、需要哪些补救动作。
+- 发布阶段：若 breaking risk 仍存在，必须同步到 `/team-release` 的放行结论或观察项。
+
+## 参考来源
+
+- [OpenAPITools/openapi-diff](https://github.com/OpenAPITools/openapi-diff)

package/docs/runbooks/api-design-evolution-walkthrough.md

@@ -0,0 +1,42 @@
+---
+version: "0.1.0"
+status: draft
+created: 2026-03-28
+updated: 2026-03-28
+owner: 工程团队
+---
+
+# API 设计与演进演练
+
+本文演示接口从设计、联调到兼容性验证的完整链路，适用于前后端协作和跨服务接口调整。
+
+## 1. 场景
+
+- 订单查询接口新增状态聚合字段
+- 前端需要新字段，旧调用方不能被破坏
+- 需要补契约说明和联调验证
+
+## 2. 推荐链路
+
+1. `/team-intake`
+2. `/team-plan`
+3. `/multi-backend`
+4. `/team-execute`
+5. `/code-review`
+6. `/verify`
+7. `/handoff`
+
+## 3. 关键输出
+
+- 接口变更说明
+- 兼容性策略
+- 联调结果
+- 回滚与降级说明
+
+## 4. 常见错误
+
+- 只说新增字段，不说兼容性
+- 后端改完才通知前端
+- 没有明确哪些调用方需要回归
+
+与后端角色说明配合阅读：[backend-engineer-daily-operations.md](backend-engineer-daily-operations.md)

package/docs/runbooks/api-lint-gates.md

@@ -0,0 +1,57 @@
+# API Lint 门禁手册
+
+本手册承接 `stoplightio/spectral` 的工程实践，用于把 OpenAPI / AsyncAPI 规范从“口头约定”升级为可执行的 lint ruleset。它是接口设计与契约治理的补充，不替代 `api-contract` 或架构评审。
+
+## 适用场景
+
+- 团队以 OpenAPI 或 AsyncAPI 维护接口文档，希望对命名、错误响应、分页、鉴权等规则做统一检查。
+- 仓库已经有 API spec 文件，但 review 还在靠人工发现风格不一致或漏填字段。
+- 需要把“API 规范应该怎样写”沉淀成能重复执行的 ruleset。
+
+## 不适用场景
+
+- 当前 API 规格尚不稳定，连基础字段和输出格式都在快速漂移。
+- 团队还没统一基本 API 设计原则，却急着上大量 lint 规则。
+- 希望用 lint 结果替代人工设计评审或兼容性判断。
+
+## 推荐落地方式
+
+1. 先把规则分层：
+   - `baseline rules`：必须满足的结构性要求，例如 operationId、response、schema 引用、错误响应
+   - `style rules`：命名、描述、tag、分页约定等风格规则
+2. 第一阶段只启用高信号规则，先压住明显缺陷，不要一开始就把所有风格问题都做成阻塞项。
+3. 本地和 CI 使用同一套 ruleset，保证开发者能复现 lint 结果。
+4. 先 lint，再做 breaking change diff；否则候选 spec 本身不稳定，diff 结论也会失真。
+5. lint 结果要回写到 API 契约和 review 结论里，而不是只留在命令行输出。
+
+## 最小门禁模型
+
+- `input layer`：稳定的 OpenAPI / AsyncAPI 文件
+- `lint layer`：ruleset 输出错误、警告和建议
+- `decision layer`：`architect`、`backend-engineer`、`qa-engineer`、`tech-lead` 判断哪些规则阻塞、哪些暂时接受
+
+工具负责指出偏差，团队负责定义规则和接受风险。
+
+## 推荐优先检查项
+
+- operationId、summary、description、tags 是否完整
+- 错误响应、鉴权要求、分页参数是否缺失
+- schema 引用、命名约定、枚举描述是否一致
+- 是否存在空 response schema、未定义错误码、含糊字段名或重复 path 设计
+
+## 反模式
+
+- 还没对齐 API 设计原则，就先把 lint 全面阻塞。
+- 本地和 CI 的 ruleset 不一致，导致 PR 报错无法复现。
+- 用 lint 替代设计 review，结果结构整齐但语义仍然有问题。
+- 只看 warning 数量，不分析哪些规则真正影响协作和兼容性。
+
+## 输出回落
+
+- 设计阶段：把规则偏差和例外说明回写到 [api-contract.md](../../templates/api-contract.md) 或方案说明。
+- 评审阶段：在 `/team-review` 或 `/code-review` 中明确哪些 lint 问题阻塞、哪些属于暂时接受的风格偏差。
+- 发布阶段：若 lint 规则属于正式门禁，结果同步到 `/team-release` 的检查项或放行前提。
+
+## 参考来源
+
+- [stoplightio/spectral](https://github.com/stoplightio/spectral)

package/docs/runbooks/api-mocking-strategy-and-lifecycle-guide.md

@@ -0,0 +1,47 @@
+---
+version: "0.1.0"
+status: draft
+created: 2026-03-28
+updated: 2026-03-28
+owner: 工程团队
+---
+
+# API Mock 策略与生命周期手册
+
+本文说明前后端并行开发时，Mock 应该如何选型、使用、同步和下线。它补的是工程实践，不替代接口契约、contract testing 或真实联调。
+
+## 1. 什么时候需要 Mock
+
+- 前端先于后端开工
+- 接口契约已基本稳定，但实现尚未交付
+- QA 需要提前准备部分验收路径
+
+## 2. Mock 的选型思路
+
+- 固定 fixture：适合稳定 happy path
+- 拦截型 mock：适合前端页面开发与交互验证
+- 轻量 HTTP mock 服务：适合多端共享同一份假数据
+- provider stub：适合后端依赖未就绪时的集成占位
+
+## 3. 生命周期管理
+
+- 立项时：明确是否允许 Mock 驱动开发
+- plan 阶段：写清楚谁维护 Mock 和何时切真实接口
+- execute 阶段：记录 Mock 覆盖的场景和已知缺口
+- 联调阶段：把 Mock 与真实接口差异回写 handoff
+- review 阶段：清理过期 Mock，避免长期漂移
+
+## 4. 最小交接要求
+
+- Mock 覆盖了哪些请求与响应
+- 哪些字段仍待真实接口确认
+- 切换真实接口的检查点
+- 哪些问题不能靠 Mock 证明
+
+## 5. 常见错误
+
+- 契约还没稳定就先写大量 Mock
+- Mock 数据和真实接口长期分叉
+- 联调完成后没有回收临时 Mock
+
+与这些文档配合阅读：[frontend-backend-parallel-integration-walkthrough.md](frontend-backend-parallel-integration-walkthrough.md)、[contract-testing-playbook.md](contract-testing-playbook.md)

package/docs/runbooks/architect-daily-operations.md

@@ -0,0 +1,63 @@
+---
+version: "0.1.0"
+status: draft
+created: 2026-03-28
+updated: 2026-03-28
+owner: 工程团队
+---
+
+# Architect 日常操作手册
+
+本文面向架构师，说明系统边界、接口契约、技术方案与风险控制如何在 Team Skills Platform 下落地。
+
+如果你想先看平台当前有哪些公开命令和能力映射，先读 [command-and-capability-matrix.md](command-and-capability-matrix.md)。
+
+## 1. 你的默认职责
+
+- 明确系统边界、依赖关系和关键约束
+- 产出 ADR、接口契约、数据模型或实施边界说明
+- 识别中长期技术风险和短期实施风险
+- 把设计结论结构化交接给研发、QA 和 tech-lead
+
+## 2. 开始设计前必须确认什么
+
+- 需求目标、范围外事项和成功标准是否清楚
+- 当前任务是接口演进、系统重构还是跨服务协作
+- 哪些约束不可打破，例如兼容性、稳定性、权限边界
+- 哪些风险需要在 plan 阶段提前暴露
+
+## 3. 设计时的固定检查
+
+- 边界是否单一清楚
+- 契约是否可消费、可验证
+- 兼容性和迁移路径是否说明
+- 非功能约束是否写明
+- 实施方是否能据此落地
+
+## 4. 应交付什么
+
+- 方案摘要
+- ADR 或替代决策记录
+- 接口或数据契约
+- 实施建议与风险提醒
+- 需要 handoff 的重点事项
+
+如果需要成文化 ADR，直接按 [artifact-standards.md](../../rules/artifact-standards.md) 中的 ADR 最小字段组织：决策信息、背景与约束、备选方案、决策结果、企业内控补充、后续动作。
+
+## 5. 常用命令组合
+
+- `/team-intake`：确认目标、范围和约束
+- `/team-plan`：把设计任务放入主链拆解
+- `/multi-backend` 或 `/plan`：做专项方案分析
+- `/tdd`：在高返工风险任务里提前锁边界行为和验证口径
+- `/handoff`：把方案交给研发与 QA
+- `/team-review`：确认方案落地后的剩余风险
+
+## 6. 常见错误
+
+- 设计只停留在概念层，没有可执行边界
+- 契约写了 happy path，没有错误和兼容策略
+- 方案已明确适合测试先行，却没有把 `/tdd` 约束前置到实现阶段
+- 复杂任务没有留下决策记录
+
+建议与这些文档配合阅读：[api-design-evolution-walkthrough.md](api-design-evolution-walkthrough.md)、[system-architecture-design-walkthrough.md](system-architecture-design-walkthrough.md)、[architect-design-conversation-example.md](architect-design-conversation-example.md)

package/docs/runbooks/architect-design-conversation-example.md

@@ -0,0 +1,83 @@
+---
+version: "0.1.0"
+status: draft
+created: 2026-03-28
+updated: 2026-03-28
+owner: 工程团队
+---
+
+# Architect 方案设计对话样例
+
+本文给出一份偏 Architect 视角的成品对话样例，重点展示怎样把系统边界、契约、兼容性和实施风险整理成可执行方案，而不是停留在概念描述。
+
+## 1. 场景
+
+- 任务：审批记录查询能力准备进入设计拆解
+- 当前输入：需求范围已经确认，需判断接口契约和 overlay 候选项
+- 目标：形成可交给研发和 QA 的结构化方案
+
+## 2. 用户怎么说
+
+```text
+请以 architect 视角处理当前任务。
+输出：系统边界、接口契约、数据约束、主要技术风险、是否需要 custom overlay。
+如果需要 custom overlay，请区分候选项和正式启用项。
+```
+
+## 3. 期望结果长什么样
+
+```text
+系统边界
+- 本次只新增审批记录查询能力，不改流程定义和历史数据
+- 前端消费查询接口，后端负责权限过滤和分页
+
+接口契约
+- 入参：订单号、审批状态、开始时间、结束时间、分页参数
+- 出参：记录列表、总数、分页信息、错误码
+
+数据约束
+- 审批状态字段保持与现有运营口径一致
+- 分页参数兼容旧客户端默认值
+
+主要技术风险
+- 若权限口径和现有查询接口不一致，可能导致结果偏差
+- 若字段命名调整过大，旧客户端兼容性会受影响
+
+company 判断
+- 私有流程引擎：候选，原因是任务涉及审批状态语义
+- 私有权限中心：候选，原因是任务涉及权限过滤
+- 正式启用：本次不启用，原因是未进入流程运行态和权限中心正式集成
+
+实施建议
+- 先冻结字段口径和权限边界，再进入实现
+- QA 需重点验证兼容性和权限场景
+```
+
+## 4. 不合格结果通常长什么样
+
+```text
+大概加一个查询接口，权限再看。
+```
+
+这类结果的问题是：
+
+- 没有接口契约
+- 没有兼容性约束
+- 没有 company 判断
+
+## 5. Architect 在对话里最容易漏什么
+
+- 错误和异常路径
+- 兼容性与迁移说明
+- overlay 候选项和未启用原因
+- 交给研发与 QA 的明确关注点
+
+## 6. 继续推进时怎么说
+
+当设计结论形成后，下一句通常是：
+
+```text
+请把上面的方案整理成可直接进入 /handoff 或 /team-plan 的内容，包含接口契约、风险、技能装配判断和实施建议。
+```
+
+与这些文档配合阅读：[architect-daily-operations.md](architect-daily-operations.md)、[system-architecture-design-walkthrough.md](system-architecture-design-walkthrough.md)、[api-design-evolution-walkthrough.md](api-design-evolution-walkthrough.md)

package/docs/runbooks/artifact-attestation-gates.md

@@ -0,0 +1,75 @@
+# Artifact Attestation 门禁手册
+
+本手册承接 `actions/attest-build-provenance` 的工程实践，用于把构建产物 provenance attestation 接入发布链、审计链和供应链治理。它补的是“这个产物是如何构建出来的”证明，不替代 SBOM、漏洞扫描或人工放行判断。
+
+## 适用场景
+
+- 仓库会发布二进制、容器镜像、压缩包或其他正式制品。
+- 团队已经开始关注 SBOM、依赖门禁或供应链基线，希望进一步证明产物来源和构建链。
+- 需要让发布记录能回答“这个 artifact 是由哪次 workflow、哪份源码、哪套 runner 构建出来的”。
+
+## 不适用场景
+
+- 当前还没有稳定发布制品，却为了追求概念完整性强行加 provenance。
+- 团队还没有明确 attestation 生成后存放在哪里、谁来验证、何时检查。
+- 期望只靠 provenance attestation 回答漏洞、许可证或业务风险问题。
+
+## 推荐落地方式
+
+1. 先把 attestation 看成发布证明链，不要一开始就把它和所有安全门禁混成一个阻塞开关。
+2. 第一阶段先固定三件事：
+   - 哪些正式制品需要 provenance
+   - attestation 与产物如何关联
+   - 发布记录在哪里能找到 attestation
+3. 将 attestation 与现有链路分层：
+   - `sbom-generation-gates` 负责成分清单
+   - `trivy-security-gates` 负责漏洞与 misconfiguration
+   - `scorecard-supply-chain-gates` 负责仓库与 workflow 基线
+   - `slsa-generator-patterns` 负责 GitHub Actions 侧更通用的 provenance 生成模式与 workflow 约束
+   - `in-toto-attestation-framework` 负责 predicate、schema 和 evidence model 设计
+   - attestation 负责构建来源与生成证明
+4. 若团队后续要接签名或对外验证，先把 attestation 生成和归档链跑稳，再补验证链。
+5. 结果必须回写到 `/team-release`、发布记录或制品元数据中，不让 attestation 只停在 workflow summary 里。
+
+## 最小门禁模型
+
+- `subject layer`：要发布的 artifact 或镜像
+- `provenance layer`：attestation 的 subject、digest、构建来源与 workflow 信息
+- `publication layer`：attestation 的存放位置与可检索方式
+- `decision layer`：`devops-engineer`、`tech-lead` 决定“缺失 attestation”是否阻塞发布
+
+重点不是“能生成一份 attestation”，而是发布后还能稳定找到并验证它。
+
+## 重点检查项
+
+- attestation 是否和实际发布出去的 artifact、镜像 digest 或 release asset 一一对应
+- 产物重新构建、补发或回滚时，attestation 是否同步更新
+- workflow 是否记录了足够的 provenance 信息，而不是只有一个孤立文件
+- 团队是否定义了 attestation 的存放位置、命名规则和发布记录回链方式
+- 后续若要对外验证，当前格式和存储方式是否能平滑扩展
+
+## 反模式
+
+- 生成了 attestation，但没人知道和哪个产物、哪个版本对应。
+- 有 SBOM 没 provenance，或有 provenance 没 SBOM，导致追溯链断层。
+- 只把 attestation 当“发布多一个文件”，没有放回 release 记录和审计链。
+- 还没跑通归档和验证链，就先把“缺失 attestation”设置成强阻塞项。
+
+## 输出回落
+
+- 构建阶段：记录哪些产物生成了 provenance attestation、文件或 URL 在哪里。
+- 发布阶段：把 attestation 链接、artifact 名称或摘要写入 `/team-release` 的发布方案、检查结果或放行结论。
+- 审计阶段：若需要追溯某次发布，必须能从 release 记录定位到对应 attestation，并反查到构建来源。
+
+## 许可证与使用边界
+
+- `actions/attest-build-provenance` 本身是 MIT。
+- 启用前应确认仓库类型、GitHub runner 版本、产物发布位置和组织级 attestations 能力边界。
+
+## 参考来源
+
+- [actions/attest-build-provenance](https://github.com/actions/attest-build-provenance)
+- [sbom-generation-gates.md](sbom-generation-gates.md)
+- [scorecard-supply-chain-gates.md](scorecard-supply-chain-gates.md)
+- [slsa-generator-patterns.md](slsa-generator-patterns.md)
+- [in-toto-attestation-framework.md](in-toto-attestation-framework.md)