@colin4k1024/tsp 2.4.4 → 2.4.6

package/docs/runbooks/iac-kubernetes-platform-walkthrough.md

@@ -1,120 +0,0 @@
----
-version: "0.1.0"
-status: draft
-created: 2026-03-29
-updated: 2026-03-29
-owner: 工程团队
----
-
-# IaC 与 Kubernetes 平台演练
-
-本文演示一个以 Helm Chart、Kubernetes manifest、policy 和发布门禁为核心的仓库，如何从环境边界澄清、验证分层到 review / release 收口完整跑通。
-
-## 1. 场景
-
-- 仓库当前主要维护 Helm Chart、Kubernetes YAML、Policy 和发布配置
-- 团队准备补齐 chart 渲染、schema 校验、policy 校验和 server-side dry-run 四层验证
-- 目标不是改业务服务代码，而是把 IaC 变更治理成可分层解释、可发布、可回滚的状态
-
-## 2. 推荐链路
-
-1. `/team-intake`
-2. `/team-plan`
-3. `/tdd`
-4. `/team-execute`
-5. `/verify`
-6. `/team-review`
-7. `/team-release`
-
-## 3. 第一步：/team-intake
-
-### 输入示例
-
-```text
-/team-intake
-目标：补齐 Kubernetes 平台仓库的 chart、schema、policy 和发布门禁
-范围：Helm Chart、manifest、policy、验证脚本、release 说明
-不做：业务服务逻辑改造
-约束：必须区分 helm unittest、kubeconform、conftest/kyverno 和 server-side dry-run 的边界
-```
-
-### 期望输出重点
-
-- 识别这是 IaC / 平台治理任务，而不是普通后端需求
-- 明确参与角色至少包括 `tech-lead`、`architect`、`qa-engineer`、`devops-engineer`
-- 风险应聚焦环境范围不清、验证层次混淆、回滚路径缺失和发布窗口不明确
-
-## 4. 第二步：/team-plan
-
-### 需要拆清的动作
-
-- chart 模板改动与 values 影响范围
-- schema 校验与 manifest 结构验证
-- policy 校验与组织级规则约束
-- server-side dry-run 与 release 前预检
-- review、release 和回滚记录位置
-
-### 合格输出应该回答
-
-1. 哪些问题属于 chart 层
-2. 哪些属于 schema 层
-3. 哪些属于 policy 层
-4. 哪些属于 API server 接收层
-5. 最终如何进入 `/team-review` 和 `/team-release`
-
-## 5. 第三步：/tdd
-
-在这类仓库里，`/tdd` 重点不是业务单测，而是先锁验证分层和完成标准：
-
-- chart、schema、policy、server-side 四层边界是否说清
-- 哪些验证结果必须进入 review
-- 哪些结果必须进入 release 与回滚说明
-- 失败时如何判断是模板问题、结构问题还是策略问题
-
-## 6. 第四步：/team-execute
-
-执行阶段通常包含：
-
-- 调整 Helm Chart 或 manifest
-- 补 Helm unittest、schema 校验与 policy 门禁
-- 补 server-side dry-run 或等价发布前预检
-- 更新 release 说明、回滚说明和 review 摘要
-
-本阶段输出至少应包含：
-
-- 变更摘要
-- 影响环境
-- 分层校验结果
-- 剩余风险和例外项
-
-## 7. 第五步：/verify
-
-Verify 阶段要回答：
-
-- chart 渲染是否符合预期
-- manifest 是否通过 schema 校验
-- policy 是否还有阻塞项
-- server-side 预检是否通过
-- 哪些风险仍需 release 阶段继续观察
-
-## 8. 第六步：/team-review 与 /team-release
-
-### Review 阶段要回答
-
-- 当前阻塞项来自哪一层验证
-- 哪些例外被暂时接受
-- 哪些变更会影响环境或回滚复杂度
-
-### Release 阶段要回答
-
-- 哪些环境将被影响
-- 回滚是回 chart、回 values 还是回 policy
-- 发布窗口、依赖条件和失败时的退回路径是什么
-
-## 9. 常见错误
-
-- 把 Helm unittest、kubeconform、policy 和 dry-run 混成一个结论
-- 只看 CI 通过，不记录环境范围和回滚方式
-- 没把验证结果回写到 review / release
-
-建议配合阅读：[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)

package/docs/runbooks/implementation-onboarding-reading-path.md

@@ -1,67 +0,0 @@
----
-version: "0.1.0"
-status: draft
-created: 2026-03-29
-updated: 2026-03-29
-owner: 工程团队
----
-
-# 实施接入阅读路径
-
-本文面向准备把 Team Skills Platform 接入新仓库的人，目标不是讲全，而是把阅读顺序压到最短。
-
-## 1. 适合谁
-
-- Tech Lead
-- Architect
-- Project Manager
-- 负责新仓库 onboarding 的实施人
-
-## 2. 先回答三个问题
-
-### 2.1 我从哪个模板起手
-
-先看 [../../examples/INDEX.md](../../examples/INDEX.md) 和 [../../examples/project-type-starter-playbook.md](../../examples/project-type-starter-playbook.md)。
-
-### 2.2 我这个项目能不能直接套现成 vertical 材料
-
-先看 [vertical-scenario-capability-matrix.md](vertical-scenario-capability-matrix.md)，再按需进入对应 walkthrough、demo script 和 execution log。
-
-### 2.3 我需要先装平台还是先跑第一条任务
-
-先看 [project-onboarding.md](project-onboarding.md)，再按最小闭环进入 [first-team-workflow-walkthrough.md](first-team-workflow-walkthrough.md)。
-
-## 3. 推荐顺序
-
-1. [../presentation/implementation-onboarding-brief.md](../presentation/implementation-onboarding-brief.md)
-2. [project-onboarding.md](project-onboarding.md)
-3. [../../examples/INDEX.md](../../examples/INDEX.md)
-4. [../../examples/project-type-starter-playbook.md](../../examples/project-type-starter-playbook.md)
-5. [vertical-scenario-capability-matrix.md](vertical-scenario-capability-matrix.md)
-6. [first-team-workflow-walkthrough.md](first-team-workflow-walkthrough.md)
-
-## 4. 接入时的最短判断
-
-- 已知项目类型：直接从 examples 模板起手
-- 已知 vertical：直接从矩阵检查 starter、walkthrough、demo 是否齐全
-- 只想先跑通主链：跳过 vertical，先走 onboarding + walkthrough
-- 需要 overlay / runbook / toolkit 边界：补看 [custom-overlay.md](custom-overlay.md)
-
-## 5. 最小执行顺序
-
-1. 运行安装与接入准备：看 [project-onboarding.md](project-onboarding.md)
-2. 准备项目级入口：从 [../../examples/project-CLAUDE.md](../../examples/project-CLAUDE.md) 或对应 vertical 模板复制
-3. 跑第一条主链：按 [first-team-workflow-walkthrough.md](first-team-workflow-walkthrough.md)
-4. 需要专项能力时，再补 [specialist-commands-playbook.md](specialist-commands-playbook.md)
-
-## 6. 常见误区
-
-- 先看完所有文档才开始接入，导致 onboarding 变成重阅读任务
-- 已经命中某个 vertical，却仍然只用通用模板起手
-- 把历史企业扩展导入区当成正式接入入口
-
-## 7. 继续往下看什么
-
-- 想按 Claude 端进入：看 [claude-usage-scenarios.md](claude-usage-scenarios.md)
-- 想按 Codex 端进入：看 [codex-usage-scenarios.md](codex-usage-scenarios.md)
-- 想给团队做培训：看 [team-training-reading-path.md](team-training-reading-path.md)

package/docs/runbooks/in-toto-attestation-framework.md

@@ -1,94 +0,0 @@
-# In-Toto Attestation 设计参考手册
-
-本手册承接 `in-toto/attestation` 的工程实践，用于帮助团队设计 attestation 的 predicate、schema 和 evidence model。它补的是“我们要证明什么、证据长什么样、证据如何串成链”这一层，不替代 `artifact-attestation-gates`、`slsa-verification-gates`、`cosign-signing-gates` 或 `policy-controller-gates`。
-
-## 适用场景
-
-- 团队已经开始做构建证明、签名或 provenance 管理，但还没有统一的 attestation 结构设计。
-- 需要把 build、test、scan、sign、approval 这些事件串成可检索、可验证、可归档的证据链。
-- 希望为不同产物定义可演进的 predicate，而不是把所有信息都塞进一个不可维护的大 JSON。
-- 需要跨团队对齐“哪些事实进入 attestation，哪些事实留在 release note、runbook 或审计记录里”。
-
-## 不适用场景
-
-- 当前还没有任何稳定的发布制品或构建链，却先讨论 attestation schema。
-- 团队只是想找一个“能生成 attestation 的工具”，而不是设计自己的证据模型。
-- 需要解决漏洞扫描、许可证审查、签名验证或集群强制策略时，把 attestation 当成万能入口。
-- 团队没有人愿意维护 predicate 版本、schema 迁移和验证规则。
-
-## 推荐落地方式
-
-1. 先回答“我们到底要证明什么”，再决定 predicate 的字段，而不是反过来先抄一个 schema。
-2. 第一阶段只设计少量高价值 predicate：
-   - `build`：源码、workflow、runner、digest、输出产物
-   - `test`：测试范围、环境、结果摘要、失败边界
-   - `scan`：扫描对象、规则集、结论、例外项
-   - `sign`：签名对象、签名主体、时间与版本
-   - `approval`：谁批准、批准范围、批准前提
-3. 采用分层模型组织 attestation：
-   - `subject layer`：被证明的 artifact、镜像、release asset 或 bundle
-   - `predicate layer`：关于 subject 的事实，按事件类型拆分
-   - `evidence layer`：签名、证书、时间戳、来源 URI、digest
-   - `policy layer`：哪些 predicate 是必需的，哪些可以选配
-4. 设计 schema 时优先考虑版本化和可演进性：
-   - 字段名稳定，新增字段向后兼容
-   - predicate type 有明确命名空间
-   - schema 版本和验证规则能一起升级
-5. 将 attestation 与现有链路分层：
-   - `artifact-attestation-gates` 负责构建产物 provenance
-   - `slsa-verification-gates` 负责独立验证
-   - `cosign-signing-gates` 负责签名与验签
-   - `policy-controller-gates` 负责在 admission 层把证据转成强制策略
-6. 结果必须回写到 `/team-release`、审计记录或制品元数据，不让 attestation 只停在某个仓库对象里。
-
-## 最小门禁模型
-
-- `subject layer`：被证明的产物或对象。
-- `predicate layer`：build/test/scan/sign/approval 等事实，按事件类型分开。
-- `evidence layer`：证据来源、签名、时间戳、digest 与可追溯链接。
-- `verification layer`：如何校验 predicate 与 subject 是否匹配。
-- `decision layer`：`architect`、`devops-engineer`、`tech-lead` 决定证据是否足以放行。
-
-重点不是“有一份 JSON”，而是这份 JSON 是否能稳定回答三个问题：
-
-- 这是什么对象。
-- 这个对象经历了什么。
-- 这些事实是谁提供、谁验证、谁批准的。
-
-## 重点检查项
-
-- predicate 是否按事件类型拆分，而不是把所有事实写进一个超大结构。
-- schema 是否有明确版本号、兼容策略和字段语义说明。
-- evidence 是否记录了 subject digest、来源 URI 和生成时间，避免“证据和对象对不上”。
-- 设计是否区分事实、判断和审批，避免把所有人类意见都塞进同一层。
-- 证据链是否能和 `artifact-attestation-gates`、`slsa-verification-gates`、`cosign-signing-gates` 互相引用。
-- 是否清楚哪些字段属于 attestation，哪些字段应留在 release note、runbook 或审计记录。
-
-## 反模式
-
-- 先选工具，再倒推 schema，最后 attestation 变成工具输出的副作用。
-- 把 build、test、scan、approval 的所有细节都堆在一份 predicate 里，后续无法演进。
-- 只有 attestation，没有 subject digest 或来源链接，导致证据无法复查。
-- schema 变更时没有版本策略，旧证据无法验证，新证据又和旧链路不兼容。
-- 把 attestation 当成“安全结论本身”，忽略了它只是证据承载层。
-
-## 输出回落
-
-- 设计阶段：把 predicate 类型、字段含义、版本号和证据来源写入设计文档或 API contract。
-- 构建阶段：把生成的 attestation 与 artifact digest、workflow、build id 或 release asset 关联起来。
-- 发布阶段：把 attestation 的定位方式、关键证据和验证结果写入 `/team-release`。
-- 审计阶段：若需要追溯某次发布，必须能从 release 记录定位到对应 attestation，并反查到 subject 和 predicate。
-
-## 许可证与使用边界
-
-- `in-toto/attestation` 采用 Apache-2.0。
-- 引入前应确认团队是否具备维护 predicate schema、版本迁移和验证规则的能力。
-- 如果只是想做“能记录构建来源”，优先走 `artifact-attestation-gates`；如果要做“验证是否可信”，优先走 `slsa-verification-gates`。
-
-## 参考来源
-
-- [in-toto/attestation](https://github.com/in-toto/attestation)
-- [artifact-attestation-gates.md](artifact-attestation-gates.md)
-- [slsa-verification-gates.md](slsa-verification-gates.md)
-- [cosign-signing-gates.md](cosign-signing-gates.md)
-- [policy-controller-gates.md](policy-controller-gates.md)

package/docs/runbooks/incident-severity-triage-tree.md

@@ -1,43 +0,0 @@
----
-version: "0.1.0"
-status: draft
-created: 2026-03-28
-updated: 2026-03-28
-owner: 工程团队
----
-
-# 事故分级与应急决策树
-
-本文用于事故发生后的前几分钟内快速分级，决定是止血、回滚还是继续排查。
-
-## 1. 快速分级
-
-- P1：关键流程不可用，影响核心用户路径
-- P2：关键流程部分可用，但错误率明显升高
-- P3：非核心路径异常或局部功能退化
-
-## 2. 决策树
-
-- 如果核心路径不可用：优先止血或回滚
-- 如果核心路径可用但波动明显：先限制影响面，再继续验证
-- 如果问题局部可控：记录问题，按 hotfix 或后续版本处理
-
-## 3. 最小止血动作
-
-- 回滚
-- 关闭入口或降级
-- 限流或隔离问题流量
-
-## 4. 什么时候必须升级
-
-- 多角色连续两轮仍无法统一结论
-- 问题已影响发布窗口或灰度计划
-- 问题已超出当前值守角色可控范围
-
-## 5. 常见错误
-
-- 先争论根因，后做止血
-- 没有单点决策人
-- 止血后没有后续动作记录
-
-相关长文档见：[production-incident-response-walkthrough.md](production-incident-response-walkthrough.md)、[hotfix-emergency-release-walkthrough.md](hotfix-emergency-release-walkthrough.md)

package/docs/runbooks/incident-triage-one-page.md

@@ -1,65 +0,0 @@
----
-version: "0.1.0"
-status: draft
-created: 2026-03-28
-updated: 2026-03-28
-owner: 工程团队
----
-
-# 事故分诊一页速查
-
-本文面向线上异常、灰度问题、回滚判断这类必须快速分诊的场景。
-
-## 1. 什么时候用这页
-
-- 灰度后出现错误率、时延或关键业务异常
-- 不确定应该先回滚、先止血还是先继续观察
-- 需要让 QA、DevOps、Tech Lead 快速形成统一动作
-
-## 2. 最短起手方式
-
-```text
-/team-review
-当前灰度期间出现异常，请按事故处理视角输出：问题等级、阻塞结论、建议动作、是否进入回滚、下一角色责任链。
-```
-
-## 3. 最短判断顺序
-
-1. 先判断是否影响核心业务和用户面
-2. 再判断是否需要立即止血或回滚
-3. 再决定是继续观察、进入 incident runbook，还是重新 review
-
-## 4. 最短结论模板
-
-```text
-评审结论
-- 结论：暂缓放量
-- 影响：审批回调时延升高，已影响部分用户
-
-建议动作
-- 立即停止扩量
-- DevOps 准备回滚路径
-- QA 补关键路径复验
-- Tech Lead 判断是否升级为正式事故处理
-```
-
-## 5. 谁该先做什么
-
-- QA：确认影响范围和复现条件
-- DevOps：准备止血和回滚动作
-- Tech Lead：做优先级和升级判断
-- 研发：定位根因并给出修复或回滚建议
-
-## 6. 快速参考顺序
-
-1. [incident-severity-triage-tree.md](incident-severity-triage-tree.md)
-2. [production-incident-response-walkthrough.md](production-incident-response-walkthrough.md)
-3. [release-rollback-recovery-walkthrough.md](release-rollback-recovery-walkthrough.md)
-
-## 7. 常见错误
-
-- 还没判断影响等级，就开始讨论技术细节
-- 已经满足回滚条件，却继续拖着观察
-- 问题已经进入事故处理，但主链结论还停留在普通 review
-
-如果你要看发布前后的完整上下文，继续看 [release-closure-one-page.md](release-closure-one-page.md) 和 [release-governance-reading-path.md](release-governance-reading-path.md)。

package/docs/runbooks/internal-developer-platform-demo-execution-log.md

@@ -1,36 +0,0 @@
----
-version: "0.1.0"
-status: draft
-created: 2026-03-29
-updated: 2026-03-29
-owner: 工程团队
----
-
-# 内部开发者平台演示执行记录
-
-本文记录一条内部开发者平台演示路径，重点展示团队如何把入口行为、模板验证、失败兜底和发布依赖整理成结构化交付链路。
-
-## 1. 场景定义
-
-- 背景：仓库维护开发者门户、自助模板和平台集成点
-- 目标：把入口交付从“功能可用”升级成“可验证、可交接、可发布”的状态
-
-## 2. 关键阶段
-
-- `/team-intake`：锁入口、模板、权限和发布前提
-- `/team-plan`：拆平台 API、模板行为和失败兜底
-- `/tdd`：定义成功 / 失败路径和人工介入条件
-- `/handoff`：把验证范围和剩余风险交给下游角色
-- `/team-review`、`/team-release`：形成正式上线结论
-
-## 3. 校验结果
-
-```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
-```

package/docs/runbooks/internal-developer-platform-demo-script.md

@@ -1,42 +0,0 @@
----
-version: "0.1.0"
-status: draft
-created: 2026-03-29
-updated: 2026-03-29
-owner: 工程团队
----
-
-# 内部开发者平台演示剧本
-
-本文是一份可直接照着讲的演示脚本，面向开发者入口、自助模板、平台 API 和失败兜底路径场景。
-
-## 1. 演示目标
-
-- 说明平台入口为什么必须同时讲成功和失败路径
-- 说明 `/tdd` 如何前置锁定模板行为和人工介入条件
-- 说明 `/handoff` 如何把开发者体验和发布前提交给下游角色
-
-## 2. 演示脚本
-
-### Step 1. 先讲开发者入口不是只有 happy path
-
-```text
-内部开发者平台最容易被低估的，不是入口本身，而是失败兜底、人工介入和发布前提。
-```
-
-### Step 2. 用 `/team-intake` 锁边界
-
-```text
-/team-intake
-目标：为内部开发者平台新增自助交付入口并补齐模板、验证和发布说明
-范围：门户入口、平台 API、模板行为、测试计划、release 说明
-不做：无关业务系统改造
-约束：必须说明失败兜底、人工介入路径、权限边界和发布前提
-```
-
-### Step 3. 用 `/handoff` 收口
-
-```text
-/handoff
-请把当前平台实现与验证结果整理成可直接交给 QA、DevOps 或下一角色的结构化内容，明确入口行为、失败兜底、已验证范围和剩余风险。
-```

package/docs/runbooks/internal-developer-platform-walkthrough.md

@@ -1,91 +0,0 @@
----
-version: "0.1.0"
-status: draft
-created: 2026-03-29
-updated: 2026-03-29
-owner: 工程团队
----
-
-# 内部开发者平台演练
-
-本文演示一个以开发者入口、自助模板、平台 API 和交付体验为核心的内部开发者平台仓库，如何从需求澄清到 handoff / release 收口完整跑通。
-
-## 1. 场景
-
-- 仓库当前主要维护开发者门户、服务模板和平台集成能力
-- 团队准备新增一个自助交付入口，并同步补齐模板行为与发布说明
-- 目标不是做单点业务功能，而是把入口体验和交付链治理成可验证、可交接、可发布的状态
-
-## 2. 推荐链路
-
-1. `/team-intake`
-2. `/team-plan`
-3. `/tdd`
-4. `/team-execute`
-5. `/handoff`
-6. `/team-review`
-7. `/team-release`
-
-## 3. 第一步：/team-intake
-
-### 输入示例
-
-```text
-/team-intake
-目标：为内部开发者平台新增自助交付入口并补齐模板、验证和发布说明
-范围：门户入口、平台 API、模板行为、测试计划、release 说明
-不做：无关业务系统改造
-约束：必须说明失败兜底、人工介入路径、权限边界和发布前提
-```
-
-## 4. 第二步：/team-plan
-
-### 需要拆清的动作
-
-- 门户入口与模板行为
-- 平台 API 与权限边界
-- 失败兜底与人工介入路径
-- handoff、review、release 收口方式
-
-## 5. 第三步：/tdd
-
-重点是先锁：
-
-- 开发者入口成功 / 失败路径
-- 模板与 API 的边界
-- 人工介入条件
-- QA 和 DevOps 需要接到哪些信息
-
-## 6. 第四步：/team-execute
-
-执行阶段通常包含：
-
-- 调整门户或模板入口
-- 调整平台 API 或编排逻辑
-- 更新交付说明和发布前提
-
-## 7. 第五步：/handoff
-
-handoff 需要明确：
-
-- 入口行为与验证范围
-- 失败兜底和人工介入方式
-- 剩余风险和发布依赖
-
-## 8. 第六步：/team-review 与 /team-release
-
-### Review 阶段要回答
-
-- 当前开发者自助体验是否已经稳定
-- 是否仍有阻塞交付的集成风险
-
-### Release 阶段要回答
-
-- 发布前提是什么
-- 出现故障时如何退回人工路径或旧入口
-
-## 9. 常见错误
-
-- 只写 happy path，不写失败兜底
-- handoff 不写清验证范围，导致 QA 重新摸索
-- release 不说明入口切换与回退方式

package/docs/runbooks/karpathy-guidelines-usage.md

@@ -1,27 +0,0 @@
-# Karpathy Guidelines Usage
-
-`karpathy-guidelines` 是一层行为护栏，不是新的主链命令，也不是 `coding-standards`、`tdd-workflow`、`verification-loop` 的替代品。
-
-## 什么时候用
-
-- 任务描述有歧义，但又很容易让代理“猜一个就开始写”
-- 变更本来应该很小，却有过度设计风险
-- 需要明确哪些地方能改、哪些地方只能记录不能顺手清理
-- 想先把“成功长什么样”说清楚，再进入 TDD 或实现
-
-## 推荐搭配
-
-1. 先用 `karpathy-guidelines` 收敛假设、简化方案、锁定改动边界和成功标准
-2. 进入实现后，用 `coding-standards` 或相应语言/框架 skill 保持代码质量
-3. 涉及新行为或 bugfix 时，接 `tdd-workflow`
-4. 收尾前，用 `verification-loop` 给出 fresh verification evidence
-
-## 不做什么
-
-- 不替你生成完整实现计划
-- 不替代语言/框架专项 skill
-- 不强制修改 `/team-*` 主链或 role agent 默认行为
-
-## 一个简短判断
-
-如果你担心代理会“误解需求、做复杂、顺手多改、没定义成功标准”，就先用 `$karpathy-guidelines`。