@colin4k1024/tsp 2.4.1 → 2.4.2

package/docs/runbooks/cosign-signing-gates.md

@@ -0,0 +1,71 @@
+# Cosign 签名与验证门禁手册
+
+本手册承接 `sigstore/cosign-installer` 的工程实践，用于把 artifact / image signing 与验证接入发布链和外部交付证明链。它补的是“这个制品是否被正式签名、能否被验证”的证据，不替代 SBOM、provenance attestation 或漏洞扫描。
+
+## 适用场景
+
+- 仓库会发布容器镜像、二进制、压缩包或其他需要对外交付的正式制品。
+- 团队已经开始生成 SBOM、attestation，希望再补齐签名和验签这一层。
+- 需要让发布记录能回答“这个产物是否由受控身份签名，消费方如何验证”。
+
+## 不适用场景
+
+- 当前还没有稳定发布制品，却为了“供应链完整”强行加签名。
+- 团队还没有明确签名身份、密钥来源、验证入口和失败处置方式。
+- 期望只靠签名就替代 provenance、SBOM、漏洞扫描或人工放行判断。
+
+## 推荐落地方式
+
+1. 先把签名范围锁定到最关键的正式制品，不要一开始给所有中间产物都加签。
+2. 第一阶段先固定三件事：
+   - 哪些 artifact / image 需要签名
+   - 签名后如何存放和回链
+   - 谁在发布或消费时负责验签
+3. 将签名与现有链路分层：
+   - `sbom-generation-gates` 负责成分清单
+   - `artifact-attestation-gates` 负责 provenance 证明
+   - Cosign 负责 artifact / image 的签名与验证
+   - `devops-engineer`、`tech-lead` 负责最终放行判断
+4. 若团队后续要做对外验证或策略控制，先把签名和验签流程跑顺，再考虑更强的 policy gate。
+5. 结果必须回写到 `/team-release`、制品说明或外部交付文档中，不让签名结果只停在 workflow 日志里。
+
+## 最小门禁模型
+
+- `subject layer`：要发布的 artifact、image 或 release asset
+- `sign layer`：签名动作、签名身份和生成结果
+- `verify layer`：验签方式、验证责任和失败处理
+- `decision layer`：`devops-engineer`、`tech-lead` 决定“缺失签名或验签失败”是否阻塞发布
+
+重点不是“跑过一个签名命令”，而是消费方能稳定验证并信任它。
+
+## 重点检查项
+
+- 签名对象是否与实际发布出去的 artifact、镜像 digest 或 release asset 一一对应
+- 团队是否定义了签名身份、签名时机和验签入口
+- 重新构建、补发或回滚时，签名是否同步更新
+- 发布记录里是否能定位到签名结果与验签方式
+- 签名失败、验签失败或签名缺失时，发布链是否有明确处置策略
+
+## 反模式
+
+- 生成了签名，但没人知道消费方怎么验证。
+- 有 attestation 没签名，或有签名没 provenance，导致证明链断层。
+- 只在 CI 里签名一次，却不把签名结果回写到发布记录。
+- 还没跑通签名与验签流程，就直接把“签名失败”设成硬阻塞，导致团队无法消化。
+
+## 输出回落
+
+- 构建阶段：记录哪些制品完成签名、签名结果在哪里、验签入口是什么。
+- 发布阶段：把签名与验签摘要写入 `/team-release` 的发布方案、检查结果或放行结论。
+- 外部交付：若需要对外提供验证说明，必须能从 release 记录直接定位签名结果和验签方式。
+
+## 许可证与使用边界
+
+- `sigstore/cosign-installer` 本身采用 Apache-2.0。
+- 启用前应确认签名身份方案、runner 环境、镜像 registry / artifact 仓库能力，以及是否需要额外的组织级策略支持。
+
+## 参考来源
+
+- [sigstore/cosign-installer](https://github.com/sigstore/cosign-installer)
+- [artifact-attestation-gates.md](artifact-attestation-gates.md)
+- [sbom-generation-gates.md](sbom-generation-gates.md)

package/docs/runbooks/cross-role-issue-triage-walkthrough.md

@@ -0,0 +1,47 @@
+---
+version: "0.1.0"
+status: draft
+created: 2026-03-28
+updated: 2026-03-28
+owner: 工程团队
+---
+
+# 跨角色问题分诊演练
+
+本文演示 QA、前端、后端、架构师和 Tech Lead 在问题归因不明确时，如何快速分诊、分流和升级，而不是互相等待或反复甩锅。
+
+## 1. 场景
+
+- QA 发现审批列表在某些权限组合下返回异常
+- 前端怀疑字段缺失，后端怀疑前端组装逻辑有误
+- 需要快速确认是契约、实现还是环境问题
+
+## 2. 推荐链路
+
+1. `/team-execute`
+2. `/verify`
+3. `/handoff`
+4. `/team-review`
+
+必要时由 tech-lead 重新拉回 `/team-intake` 或 `/team-plan` 收口。
+
+## 3. 分诊时的关键输出
+
+- 问题现象和复现条件
+- 初步归类：前端、后端、契约、环境或待确认
+- 当前责任角色和下一步动作
+- 是否阻塞当前里程碑
+
+## 4. 什么时候要升级
+
+- 连续两轮定位后仍无明确归因
+- 问题跨多个角色边界
+- 风险会影响上线或灰度计划
+
+## 5. 常见错误
+
+- 直接争论谁负责，而不先固化现象
+- 问题在多个渠道讨论，没有统一事实源
+- 分诊完没有生成可执行的下一步动作
+
+与这些文档配合阅读：[bug-fix-complete-walkthrough.md](bug-fix-complete-walkthrough.md)、[team-command-output-contracts.md](team-command-output-contracts.md)

package/docs/runbooks/cursor-quick-start.md

@@ -0,0 +1,123 @@
+---
+version: "2.3.0"
+status: draft
+created: 2026-03-28
+updated: 2026-04-18
+owner: 工程团队
+doc_tier: entry
+last_verified: 2026-04-18
+source_of_truth:
+  - ../../README.md
+  - ../../AGENTS.md
+  - ./team-skills-usage.md
+---
+
+# Cursor Quick Start — Team Skills Platform
+
+> 参考对象：需要在 Cursor 编辑器中使用 Team Skills Platform 的工程师。
+
+## 1. 安装
+
+```bash
+node scripts/build-platform-artifacts.js
+./scripts/install-cursor.sh
+
+# 指定自定义路径
+CURSOR_HOME_DIR=/path/to/cursor ./scripts/install-cursor.sh
+```
+
+## 2. 安装后目录结构
+
+```text
+~/.cursor/
+├── plugins/team-skills-platform/
+│   ├── .cursor-plugin/
+│   ├── skills/                     # 当前正式技能目录（统一平铺）
+│   ├── commands/                   # 团队主链 + specialist 命令
+│   ├── rules/
+│   ├── agents/
+│   │   ├── roles/
+│   │   └── specialists/
+│   ├── hooks/                      # 用户可见 hook 入口
+│   ├── scripts/hooks/              # 当前 JS runtime hooks
+│   ├── contexts/
+│   ├── examples/
+│   └── mcp-configs/
+└── rules/                          # Cursor MDC 规则输出
+```
+
+Cursor 安装输出只保留当前 JS runtime 入口，不再把旧 Python hook 文件名当成现行能力。
+
+### 2.1 可选能力检查：Graphify / GitNexus
+
+如果你准备在 brownfield 项目中启用代码图谱能力，安装后可以先做预检查：
+
+```bash
+npm run graphify:doctor
+npm run gitnexus:doctor
+```
+
+预检查仅验证环境，不会自动安装依赖。Graphify 适合轻量结构证据，GitNexus 适合 MCP 查询、impact 和 detect_changes；若失败，按 [troubleshooting.md](troubleshooting.md) 的对应章节处理。
+
+## 3. 在 Cursor 中怎么进入主链
+
+- 公开入口统一从 `/team-help` 开始
+- 正式任务产出要通过 `npm run artifact:persist -- ...` 回写到项目仓库
+- specialist 结论仍需回落到 `/handoff` 或 `/team-*`
+
+## 4. 在 Cursor 中使用
+
+### 4.1 引用角色 Agent
+
+```text
+请以 Tech Lead 角色帮我拆解这个需求。
+参考：~/.cursor/plugins/team-skills-platform/agents/roles/tech-lead.md
+```
+
+### 4.2 使用团队命令
+
+```text
+先执行 /team-help，判断当前是先 intake、plan，还是先补 brownfield / readiness 证据。
+```
+
+```text
+执行 /team-plan 流程，定义见：
+~/.cursor/plugins/team-skills-platform/commands/team-plan.md
+```
+
+### 4.3 引用 Skill
+
+```text
+读取 ~/.cursor/plugins/team-skills-platform/skills/systematic-debugging/SKILL.md 并帮我定位这个 bug。
+```
+
+## 5. 常用命令速查
+
+| 命令 | 用途 |
+|------|------|
+| `/team-help` | 根据当前阶段、artifacts 与阻塞项推荐下一步 |
+| `/team-intake` | 接收需求并锁定目标、范围、约束 |
+| `/team-plan` | 收口 challenge / design / readiness，并拆解里程碑 |
+| `/team-execute` | 消费 readiness proof 执行实现 |
+| `/team-review` | 做方案、质量、测试和放行评审 |
+| `/team-release` | 做发布准备、上线检查与回滚保障 |
+| `/team-closeout` | 在观察窗口结束后做最终收口 |
+| `/handoff` | 在角色间做结构化交接 |
+| `/plan` | Planner specialist 规划入口 |
+| `/code-review` | Code Reviewer specialist 入口 |
+| `/tdd` | TDD 先行入口 |
+| `/build-fix` | 构建错误修复入口 |
+
+## 6. 重新安装 / 更新
+
+```bash
+node scripts/build-platform-artifacts.js
+./scripts/install-cursor.sh
+```
+
+## 7. 相关文档
+
+- [CLAUDE.md](../../CLAUDE.md) — 平台总览
+- [claude-quick-start.md](claude-quick-start.md) — Claude 快速上手
+- [opencode-quick-start.md](opencode-quick-start.md) — OpenCode 快速上手
+- [team-skills-usage.md](team-skills-usage.md) — 完整使用手册

package/docs/runbooks/custom-overlay.md

@@ -0,0 +1,115 @@
+# Custom Overlay 扩展机制
+
+> 本文说明如何通过 custom overlay 为 TSP（Team Skills Platform）叠加团队专属的 skills、rules 和 runbook，而无需 fork 或修改主仓库。
+
+---
+
+## 什么是 Custom Overlay
+
+Custom overlay 是一种非侵入式扩展机制：
+
+- 你的团队或组织在**独立私有仓库**中维护自己的 skills、rules、runbook；
+- 安装时通过 `--overlay <id>` 叠加到平台安装目标上；
+- 主仓库（TSP）不感知 overlay 内容，overlay 不影响主仓库更新和升级。
+
+---
+
+## 典型使用场景
+
+| 场景 | 说明 |
+|------|------|
+| 内部组件规范 | 将公司内部使用的框架、组件、中间件规范封装为 skill |
+| 私有 runbook | 将上线流程、审批 SOP、合规检查表封装为 runbook |
+| 团队约定 | 将 naming convention、分支策略等封装为 rule |
+| 行业领域知识 | 将特定行业的背景知识封装为 context |
+
+---
+
+## Overlay 仓库结构
+
+建议按如下结构组织 overlay 仓库：
+
+```
+my-org-overlay/
+├── overlay.yaml          # overlay 元信息
+├── skills/               # 团队专属 skills（同 TSP skills/ 结构）
+│   └── my-internal-skill/
+│       └── SKILL.md
+├── rules/                # 团队专属 rules
+│   └── my-internal-rule.md
+├── contexts/             # 可选：团队专属 context 模板
+└── docs/
+    └── runbooks/         # 可选：团队专属 runbook
+```
+
+### overlay.yaml 示例
+
+```yaml
+id: my-org
+name: My Org Internal Overlay
+version: 1.0.0
+description: 内部规范和领域知识扩展
+source: git+https://github.com/my-org/tsp-overlay.git
+```
+
+---
+
+## 安装方式
+
+### 通过 Node.js 安装脚本叠加 overlay
+
+```bash
+# 先安装基础 profile，再叠加 overlay
+node scripts/install-apply.js --profile team --target claude --overlay my-org
+
+# 多个 overlay 可以叠加
+node scripts/install-apply.js --profile full --target claude \
+  --overlay my-org \
+  --overlay my-team-specific
+
+# 预览安装计划（不写入文件）
+node scripts/install-plan.js --profile team --target claude --overlay my-org
+```
+
+### 通过 npx 安装
+
+```bash
+npx @colin4k1024/tsp --target claude --profile team --overlay my-org
+```
+
+---
+
+## Overlay 与主仓库的关系
+
+```
+TSP 主仓库（公开）
+  └── skills/        ← 通用 skills（195+）
+  └── rules/         ← 通用规则
+  └── commands/      ← 通用命令
+       ↑ 叠加
+My Org Overlay（私有）
+  └── skills/        ← 团队专属 skills
+  └── rules/         ← 团队专属规则
+```
+
+- 同名文件：overlay 优先级更高，会覆盖主仓库同名文件；
+- 不同名文件：直接合并，两者共存；
+- 主仓库升级不影响 overlay，overlay 独立维护版本。
+
+---
+
+## 注意事项
+
+1. **overlay 中不要包含密钥或凭据**，即使是私有仓库，也应遵守 secret management 最佳实践；
+2. overlay 仓库建议设置 access control，仅授权团队成员访问；
+3. 建议在 overlay 的 `overlay.yaml` 中声明其兼容的 TSP 版本范围；
+4. 如果 overlay 中的 skill 需要在 TSP 社区共享，可参考 [external-capability-intake.md](external-capability-intake.md) 流程提 PR 贡献到主仓库。
+
+---
+
+## 社区贡献
+
+如果你的团队开发了通用性的 skills、rules 或 runbook，欢迎贡献到 TSP 主仓库：
+
+- 参考贡献流程：[CONTRIBUTING.md](../../CONTRIBUTING.md)
+- 社区 overlay 注册（可选）：在 [discussions](https://github.com/Colin4k1024/tsp/discussions) 分享你的 overlay

package/docs/runbooks/data-ml-pipeline-demo-execution-log.md

@@ -0,0 +1,141 @@
+---
+version: "0.1.0"
+status: draft
+created: 2026-03-29
+updated: 2026-03-29
+owner: 工程团队
+---
+
+# 数据与 ML Pipeline 演示执行记录
+
+本文记录一条数据 / ML pipeline 演示路径，重点展示团队如何把任务编排、数据质量、异常样本、回填边界和 release 收口整理成正式治理链路。
+
+## 1. 场景定义
+
+### 背景
+
+- 仓库当前维护批处理任务、特征计算和结果汇总
+- 团队准备新增一个特征计算任务，并同步补齐质量验证和回填说明
+- 希望避免“任务能跑，但质量和下游影响说不清”的交付状态
+
+### 演示目标
+
+- 让观众理解任务结果、数据质量和回填影响不是一个结论
+- 让观众看到 `/tdd` 如何前置锁定数据标准
+- 让观众看到 `/verify` 如何把异常样本和下游影响正式回写到 review / release
+
+## 2. 阶段 1：/team-intake
+
+### 输入
+
+```text
+/team-intake
+目标：为数据流水线新增特征计算任务并补齐质量与回填验证
+范围：任务编排、转换逻辑、质量校验、结果汇总、测试计划
+不做：分析台 UI 改造
+约束：必须说明数据口径、批处理窗口、失败重试、回填范围和下游影响
+```
+
+### 产出
+
+| 字段 | 内容 |
+|------|------|
+| 任务类型 | 数据 / pipeline 治理 |
+| 主体对象 | 任务编排、质量校验、回填说明、release 观察 |
+| 主要风险 | 数据口径不清、异常样本失控、下游影响不明 |
+| 收口要求 | review / release 必须承接任务结果与回填结论 |
+
+## 3. 阶段 2：/team-plan
+
+### 拆解结果
+
+| 模块 | 动作 | 收口位置 |
+|------|------|----------|
+| 任务层 | 调整编排与依赖 | pipeline |
+| 口径层 | 说明转换边界与成功阈值 | docs / verify |
+| 质量层 | 汇总异常样本与重试结果 | verify / review |
+| 回填层 | 说明回填范围与下游影响 | release |
+
+### 关键判断
+
+- 任务运行成功不等于数据质量达标
+- 回填边界和下游影响必须进入正式结论，而不是附带说明
+
+## 4. 阶段 3：/tdd
+
+### 定义的完成标准
+
+```text
+1. 数据口径、成功阈值和窗口边界清晰
+2. 异常样本、失败重试和回填范围可解释
+3. verify 能汇总任务结果、质量和下游影响
+4. review / release 能承接正式结论
+5. 仓库校验通过
+```
+
+## 5. 阶段 4：/team-execute
+
+### 执行批次
+
+#### 批次 A：任务与转换
+
+- 调整任务编排
+- 调整转换逻辑
+
+#### 批次 B：质量与异常样本
+
+- 补质量校验
+- 汇总异常样本与重试结果
+
+#### 批次 C：回填与发布收口
+
+- 说明回填边界
+- 说明下游影响和发布观察项
+
+## 6. 阶段 5：/verify
+
+### Verify 结果
+
+| 检查项 | 判断 |
+|--------|------|
+| 任务结果 | 已确认 |
+| 数据质量 | 已确认 |
+| 异常样本 | 已确认 |
+| 回填影响 | 已确认 |
+| Release 收口 | 已确认 |
+
+## 7. 阶段 6：/team-review 与 /team-release
+
+### Review 结论
+
+- 当前变更已经从“任务完成”升级为“结果可解释、可追溯”
+- 例外项与待观察项已形成正式记录
+
+### Release 结论
+
+- 发布记录说明了任务窗口、回填边界和下游影响
+- 一旦异常，可快速决定回退任务、暂停回填或阻断下游消费
+
+## 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. 推荐搭配材料
+
+- [data-ml-pipeline-demo-script.md](data-ml-pipeline-demo-script.md)
+- [data-ml-pipeline-walkthrough.md](data-ml-pipeline-walkthrough.md)
+- [../../examples/data-ml-pipeline-CLAUDE.md](../../examples/data-ml-pipeline-CLAUDE.md)

package/docs/runbooks/data-ml-pipeline-demo-script.md

@@ -0,0 +1,102 @@
+---
+version: "0.1.0"
+status: draft
+created: 2026-03-29
+updated: 2026-03-29
+owner: 工程团队
+---
+
+# 数据与 ML Pipeline 演示剧本
+
+本文是一份可直接照着讲的演示脚本，面向数据口径、任务编排、质量校验、回填边界和下游影响场景。
+
+## 1. 演示目标
+
+- 说明 pipeline 任务为什么不能只看“任务跑完了”
+- 说明 `/tdd` 如何前置锁定数据口径、回填和质量标准
+- 说明 `/verify` 如何把任务结果、异常样本和下游影响收敛成正式结论
+
+## 2. 适用对象
+
+- 需要介绍数据 / pipeline 交付方式的 Tech Lead
+- 需要解释数据口径与回填风险的后端 / 数据负责人
+- 需要向团队说明 verify 为什么要看异常样本与窗口约束的讲解人
+
+## 3. 演示时长建议
+
+- 5 分钟：讲数据口径、窗口、回填三类风险
+- 10 分钟：再讲 `/tdd` 与 `/verify`
+- 15 分钟：完整走一遍 intake -> plan -> tdd -> execute -> verify -> review/release
+
+## 4. 演示脚本
+
+### Step 1. 先用 1 分钟讲清 pipeline 任务在治理什么
+
+建议讲法：
+
+```text
+数据 / pipeline 仓库最容易被低估的，不是任务代码，而是数据口径、异常样本、回填窗口和下游影响。
+如果这些不前置，任务即使跑完，也不代表可以安全上线。
+```
+
+### Step 2. 用 `/team-intake` 讲清任务边界
+
+建议输入：
+
+```text
+/team-intake
+目标：为数据流水线新增特征计算任务并补齐质量与回填验证
+范围：任务编排、转换逻辑、质量校验、结果汇总、测试计划
+不做：分析台 UI 改造
+约束：必须说明数据口径、批处理窗口、失败重试、回填范围和下游影响
+```
+
+### Step 3. 用 `/team-plan` 说明如何拆分数据任务
+
+建议输入：
+
+```text
+/team-plan
+基于当前 intake 结果，拆任务编排、数据质量、异常样本、回填影响和 release 收口动作。
+输出必须指出哪些完成标准应先进入 /tdd，哪些证据最终应由 /verify 汇总。
+```
+
+### Step 4. 用 `/tdd` 讲“先锁口径、质量和回填标准”
+
+建议输入：
+
+```text
+/tdd
+基于当前 /team-plan 结果，先定义数据口径、成功阈值、异常样本、失败重试、回填边界和下游影响的完成标准。
+```
+
+### Step 5. 用 `/team-execute` 讲实际收敛动作
+
+建议讲法：
+
+```text
+执行阶段通常会先调任务编排和转换逻辑，再补质量校验与结果汇总，最后补回填和下游影响说明。
+```
+
+### Step 6. 用 `/verify` 收口
+
+建议输入：
+
+```text
+/verify
+请基于当前 pipeline 改动，输出任务结果、数据质量、异常样本、回填影响和成本窗口，并整理成可直接进入 /team-review 或 /team-release 的结论。
+```
+
+## 5. 建议演示顺序
+
+1. 先讲数据口径、窗口、回填三类风险
+2. 再展示 `/team-intake` 与 `/team-plan`
+3. 然后讲 `/tdd`
+4. 再讲 `/team-execute`
+5. 最后讲 `/verify`、`/team-review` 和 `/team-release`
+
+## 6. 演示后建议发给观众的材料
+
+- [data-ml-pipeline-demo-execution-log.md](data-ml-pipeline-demo-execution-log.md)
+- [data-ml-pipeline-walkthrough.md](data-ml-pipeline-walkthrough.md)
+- [../../examples/data-ml-pipeline-CLAUDE.md](../../examples/data-ml-pipeline-CLAUDE.md)