@colin4k1024/tsp 2.4.1 → 2.4.3

package/docs/runbooks/runtime-capabilities-overview.md

@@ -0,0 +1,113 @@
+---
+version: "2.3.0"
+status: draft
+created: 2026-03-29
+updated: 2026-04-18
+owner: 工程团队
+---
+
+# Runtime 能力总览
+
+本文解释 Team Skills Platform 里那些“不是你手动输入的命令，但会改变会话行为”的后台能力。当前公开契约已经收口到 JavaScript runtime：以 `hooks/hooks.json` 为配置入口，以 `scripts/hooks/*.js` 为执行入口，不再使用已删除的 Python hook 文件名。
+
+## 1. 这份文档回答什么
+
+- 当前 runtime 的真实入口在哪里
+- `/team-help`、`artifact:persist` 和后台 hooks 是什么关系
+- Claude 安装后哪些 JS hooks 会真正影响会话
+- 长会话、memory、audit、budget 和 governance 信号如何落盘
+
+## 2. 当前运行时分层
+
+### 2.1 配置入口
+
+- `hooks/hooks.json`：Claude hooks 的唯一声明式配置入口
+- `scripts/install-platform.js`：legacy Claude 安装时负责复制 `scripts/hooks/`、清理旧 `.py` 引用，并把当前 JS hooks 合并到 `settings.json`
+
+### 2.2 执行入口
+
+- `scripts/hooks/session-start-bootstrap.js`：SessionStart bootstrap
+- `scripts/hooks/session-start.js`：加载 `docs/memory/project-context.md`、session summary 等上下文
+- `scripts/hooks/pre-compact.js`：PreCompact 前的高价值状态整理
+- `scripts/hooks/suggest-compact.js`：在长会话中提示人工 compact
+- `scripts/hooks/session-end.js`：Stop 阶段持久化 session 摘要
+- `scripts/hooks/session-end-marker.js`：SessionEnd 生命周期标记
+- `scripts/hooks/cost-tracker.js`：记录 token / cost 指标
+- `scripts/hooks/governance-capture.js`：采集治理与审批相关信号
+- `scripts/hooks/mcp-health-check.js`：MCP 健康检查
+- `scripts/hooks/quality-gate.js`：编辑后质量门禁
+
+### 2.3 状态与存储
+
+- `scripts/lib/state-store/`：runtime 状态存储入口
+- `docs/memory/project-context.md`：主链共享项目上下文
+- `docs/memory/decisions.md`、`docs/memory/lessons-learned.md`：轻量项目记忆
+- `docs/memory/sessions/`：session continuity 落点
+- `~/.claude/metrics/costs.jsonl`：cost tracker 输出
+- `~/.claude/memory/audit/`：本地 audit 查询输入
+
+## 3. 关键能力说明
+
+### 3.1 Session memory
+
+- 触发点：`session-start-bootstrap.js`、`session-start.js`、`session-end.js`
+- 作用：会话开始时恢复项目上下文、最近摘要和待办；Stop 阶段把本轮摘要写回 session continuity 文件
+- 用户侧影响：重新进入任务时，更容易保持 `/team-plan`、`/team-execute`、`/team-review` 的连续性
+
+### 3.2 Governance capture
+
+- 触发点：`governance-capture.js`
+- 作用：检测 secrets、approval-required 操作、敏感路径写入等治理信号
+- 用户侧影响：在高风险 Bash / Edit / Write 行为上留痕，可为后续 review 或 release 说明补证据
+
+### 3.3 Cost awareness
+
+- 触发点：`cost-tracker.js`
+- 作用：记录 token、模型与成本估算，辅助长会话预算判断
+- 用户侧影响：可以用 `node scripts/query-audit-logs.js --summary-only` 或直接查看 `~/.claude/metrics/costs.jsonl` 了解会话成本
+
+### 3.4 Compact readiness
+
+- 触发点：`suggest-compact.js`、`pre-compact.js`
+- 作用：在进入 compact 前整理状态，在高上下文压力下给出压缩提示
+- 用户侧影响：长任务中更容易知道什么时候该手动 compact，而不是在主链中段突然失去上下文
+
+### 3.5 MCP health
+
+- 触发点：`mcp-health-check.js`
+- 作用：在 MCP 调用前后记录健康状态，降低“工具看起来可用但实际已失效”的误判
+
+### 3.6 Quality after edits
+
+- 触发点：`quality-gate.js` 以及 Stop 阶段的格式化 / typecheck hook
+- 作用：在 Edit / Write 后补做最小质量闸口，避免把明显坏状态直接带到 `/handoff` 或 `/team-review`
+
+## 4. 一条典型 runtime 流水线
+
+1. SessionStart：`session-start-bootstrap.js` 调度 `session-start.js`
+2. 读取 `docs/memory/project-context.md` 与 session continuity 文件
+3. 用户通过 `/team-help` 判断当前该进入哪条主链命令
+4. `/team-intake`、`/team-plan`、`/team-execute` 等命令通过 `artifact:persist` 把正式输出落到 `docs/artifacts/`
+5. PreToolUse / PostToolUse 期间，`governance-capture.js`、`mcp-health-check.js`、质量与观察类 hooks 持续提供后台信号
+6. 长会话中，`suggest-compact.js` 给出 compact 提示，`pre-compact.js` 在真正 compact 前整理关键状态
+7. Stop：`session-end.js`、`cost-tracker.js` 等 JS hooks 在响应结束后持久化摘要与指标
+8. SessionEnd：`session-end-marker.js` 记录生命周期收尾
+
+## 5. 和 `/team-*` 主链是什么关系
+
+- `/team-help` 是唯一公开入口：负责根据 artifacts、handoff 和当前阶段决定下一步
+- `artifact:persist` 是主链输出的唯一落盘通道：负责把 PRD、delivery-plan、execute-log、handoff、release/closeout artifact 写入仓库
+- runtime hooks 不是第二套 workflow：它们只负责补上下文、记忆、治理和质量信号，不替代 `/team-*`
+
+## 6. 当前推荐查看路径
+
+- 想先看公开命令与能力映射：看 [command-and-capability-matrix.md](command-and-capability-matrix.md)
+- 想先看接入与落盘动作：看 [team-skills-usage.md](team-skills-usage.md) 和 [project-onboarding.md](project-onboarding.md)
+- 想先体验 Claude：看 [claude-quick-start.md](claude-quick-start.md)
+- 想先理解 ECC 增强层与主链如何配合：看 [ecc-harness-usage.md](ecc-harness-usage.md)
+
+## 7. 常见误解
+
+- 误解一：runtime 还是 Python hooks。当前 active surface 已切到 `scripts/hooks/*.js`
+- 误解二：`/team-help` 只是说明文案。它现在是公开主链唯一入口
+- 误解三：memory 只靠 hook 自动生成。正式任务产出仍必须通过 `artifact:persist` 写入 `docs/artifacts/`、`docs/adr/` 和 `docs/memory/`

package/docs/runbooks/sbom-generation-gates.md

@@ -0,0 +1,71 @@
+# SBOM 生成与发布门禁手册
+
+本手册承接 `anchore/sbom-action` 的工程实践，用于把构建产物、容器镜像和发布制品的 SBOM 生成、归档与发布追溯接入交付链。它补的是“我们到底交付了什么”的可追溯证据，不替代漏洞扫描、代码 review 或发布放行判断。
+
+## 适用场景
+
+- 仓库会构建二进制、容器镜像、压缩包或其他可发布产物。
+- 团队希望把产物依赖清单从“构建时临时知道”变成可归档、可追溯、可对外或对内复查的交付物。
+- 发布链已经开始关注镜像扫描、依赖门禁或供应链治理，希望再补齐 SBOM 这一层证据。
+
+## 不适用场景
+
+- 当前仓库没有稳定产物，只有纯脚本或一次性实验代码，却为了追热点强行接 SBOM。
+- 团队还没有明确“SBOM 产出后放在哪里、谁消费、如何验证”的责任链。
+- 期望只靠 SBOM 文件就回答漏洞、许可证或 provenance 的全部问题。
+
+## 推荐落地方式
+
+1. 先从最关键的发布产物开始，不要一开始把所有中间产物都做成 SBOM。
+2. 第一阶段优先固定三件事：
+   - 生成时机：构建后、发布前
+   - 产物范围：二进制、容器镜像或压缩包
+   - 存放位置：workflow artifact、release asset 或制品仓库
+3. 将 SBOM 与现有链路分层：
+   - `dependency-review-gates` 负责依赖变更与许可证风险
+   - `trivy-security-gates` 负责漏洞、misconfiguration 和 secret 扫描
+   - `scorecard-supply-chain-gates` 负责仓库级供应链基线
+   - SBOM 负责交付产物的成分清单与后续追溯
+4. 若团队后续要接 attestation、签名或 provenance，先把 SBOM 生成稳定下来，再扩展到证明链。
+5. 结果必须回写到 `/team-release`、发布记录或制品说明中，不让 SBOM 只停在 CI artifact 目录里。
+
+## 最小门禁模型
+
+- `subject layer`：需要发布或归档的制品
+- `inventory layer`：SBOM 内容、格式和生成时间点
+- `publication layer`：SBOM 如何随产物一起归档、上传或发布
+- `decision layer`：`devops-engineer`、`tech-lead` 决定是否把“缺失 SBOM”视为阻塞项
+
+重点不是“生成过一次”，而是让交付物和 SBOM 始终能对应上。
+
+## 重点检查项
+
+- 是否为真正要交付的产物生成了 SBOM，而不是只对源码目录做一次泛扫
+- SBOM 是否和产物版本、镜像 digest 或 release 记录正确关联
+- 团队是否统一了格式和存储策略，例如 SPDX、CycloneDX、artifact 或 release asset
+- 重新构建或重发版时，SBOM 是否会同步更新，而不是长期沿用旧文件
+- SBOM 是否能被后续漏洞扫描、归档审计或第三方追溯流程消费
+
+## 反模式
+
+- 生成了 SBOM，但没人知道文件在哪、对应哪个版本或哪个镜像 digest。
+- 只在源码层生成一次 SBOM，却不覆盖真正发布出去的产物。
+- 把 SBOM 当漏洞扫描报告使用，忽略它本质上是“成分清单”。
+- 发布链已经依赖镜像和二进制，却没有把 SBOM 和版本记录一起保存。
+
+## 输出回落
+
+- 构建阶段：在构建记录中注明哪些产物生成了 SBOM、生成格式和存放位置。
+- 发布阶段：把 SBOM 链接、文件名或 artifact 位置写入 `/team-release` 的发布方案、检查结果或放行结论。
+- 审计阶段：若团队需要事后追溯某个版本的成分清单，必须能从 release 记录直接定位到对应 SBOM。
+
+## 许可证与使用边界
+
+- `anchore/sbom-action` 采用 Apache-2.0。
+- 如果后续要把 SBOM 发布到对外仓库、镜像 registry 或和 attestation 绑定，需要再单独核对产物可见性、格式规范与合规要求。
+
+## 参考来源
+
+- [anchore/sbom-action](https://github.com/anchore/sbom-action)
+- [trivy-security-gates.md](trivy-security-gates.md)
+- [scorecard-supply-chain-gates.md](scorecard-supply-chain-gates.md)

package/docs/runbooks/scorecard-supply-chain-gates.md

@@ -0,0 +1,82 @@
+# Scorecard 供应链基线门禁手册
+
+本手册承接 `ossf/scorecard-action` 的工程实践，用于把仓库级供应链基线检查接入安全 review、workflow 评审和发布治理。它补的是“仓库和交付链本身是否健康”的证据，不替代依赖、代码、镜像或 IaC 扫描。
+
+## 适用场景
+
+- 变更涉及 `.github/workflows/`、GitHub Actions 权限、release automation、签名流程或第三方 action 引入。
+- 团队希望把分支保护、token 权限、action pinning、发布流程和基本供应链卫生前置成明确检查项。
+- 仓库已经有依赖、代码或镜像扫描，但还缺“仓库级供应链基线”视角。
+
+## 不适用场景
+
+- 仓库没有 GitHub Actions、没有发布工作流，也不依赖 GitHub 原生仓库治理能力。
+- 团队还没有能力处理基础治理项，却期望靠一个分数替代具体整改。
+- 只想把 Scorecard 当徽章或数字展示，而不是把它转成可执行的 triage 结论。
+
+## 推荐落地方式
+
+1. 先把 Scorecard 当“基线审计”，不要直接把总分当门禁。
+2. 第一阶段优先关注高信号检查项：
+   - `Token-Permissions`
+   - `Pinned-Dependencies`
+   - `Branch-Protection`
+   - `Dangerous-Workflow`
+   - `Binary-Artifacts`
+3. 将 Scorecard 与现有安全链分层：
+   - `dependency-review-gates` 负责依赖漏洞与许可证变化
+   - `codeql-pr-security-gates` 负责代码级语义问题
+   - `actionlint-workflow-gates` 负责 workflow 语法、结构和常见 shell 误用
+   - `github-token-permissions-baseline` 负责把 workflow 真实运行收敛成 job 级最小权限建议
+   - `zizmor-workflow-audits` 负责 workflow 安全面的细粒度审计
+   - `trivy-security-gates` 负责镜像、文件系统和 IaC 风险
+   - Scorecard 负责仓库、workflow 和供应链基线
+   - `runner-egress-hardening` 负责 GitHub Actions runner 运行时的出站访问控制与监测
+4. 若仓库是私有仓库或使用结果发布功能，先确认 GitHub 环境和权限要求，不要默认 public repo 的默认做法可直接照搬。
+5. 结果必须回写到 `/code-review`、`/team-review` 或架构/安全治理结论中，不让供应链基线结果只停在 action 页面里。
+
+## 最小门禁模型
+
+- `repo layer`：仓库策略、workflow 配置、依赖 pinning、发布与签名流程
+- `score layer`：Scorecard 检查项与结果
+- `triage layer`：确认哪些是当前变更新增问题、哪些是存量治理债务
+- `decision layer`：安全评审角色、`code-reviewer`、`tech-lead` 决定是否阻塞或进入治理 backlog
+
+重点不是追总分，而是让关键检查项变成稳定约束。
+
+## 重点检查项
+
+- GitHub token 是否最小权限，是否存在过宽 `contents: write`、`packages: write` 等权限
+- 第三方 action 是否 pin 到 commit SHA，而不是只用浮动 tag
+- 分支保护、必需 review、关键 CI 是否真正启用
+- workflow 是否存在危险触发方式、脚本注入或不受控的外部输入
+- 发布流程是否绕过签名、审计或 artifact provenance 要求
+
+## 反模式
+
+- 只盯总分涨跌，不分析具体是哪一个检查项失分。
+- 发现 workflow / token 风险后，只记在 action 日志里，没有回到 review 或治理计划。
+- 仓库已经大量使用第三方 action，却不做 pinning 和权限收敛。
+- 把存量治理债务和本次变更新增风险混在一起，导致所有 PR 都被历史问题拖死。
+
+## 输出回落
+
+- PR 阶段：把高优先级 Scorecard 检查项和 triage 结论写入 review 摘要。
+- 团队协作：在 `/team-review` 中说明哪些问题属于仓库级供应链基线、哪些需要后续治理而不是阻塞当前功能。
+- 治理阶段：若 workflow、发布权限或分支保护存在结构性风险，应沉淀到 ADR、治理待办或发布整改计划。
+
+## 许可证与使用边界
+
+- `ossf/scorecard-action` 本身采用 Apache-2.0。
+- 公开仓库与私有仓库的启用条件、结果发布和权限要求不同，接入前要先核对仓库类型与 GitHub 能力边界。
+
+## 参考来源
+
+- [ossf/scorecard-action](https://github.com/ossf/scorecard-action)
+- [dependency-review-gates.md](dependency-review-gates.md)
+- [codeql-pr-security-gates.md](codeql-pr-security-gates.md)
+- [actionlint-workflow-gates.md](actionlint-workflow-gates.md)
+- [github-token-permissions-baseline.md](github-token-permissions-baseline.md)
+- [zizmor-workflow-audits.md](zizmor-workflow-audits.md)
+- [trivy-security-gates.md](trivy-security-gates.md)
+- [runner-egress-hardening.md](runner-egress-hardening.md)

package/docs/runbooks/secret-scanning-gates.md

@@ -0,0 +1,85 @@
+# Secret Scanning 门禁手册
+
+本手册承接 `gitleaks/gitleaks` 的工程实践，用于把仓库级 secret 扫描接入 PR、默认分支与发布流程。它补的是“在代码进入主链前尽早发现硬编码密钥、token、凭证和误提交 secret”这一层，不替代人工 review、依赖门禁、运行时密钥管理或发布放行判断。
+
+## 适用场景
+
+- PR 直接涉及 `.env`、配置文件、示例文件、测试数据、脚本、CI 配置或文档中的敏感字段。
+- 仓库里已经发生过 secret 误提交，希望把“发现后再处理”前置成“合并前先拦住”。
+- 需要同时扫描当前工作区、PR diff 和历史提交，区分新引入问题与既有存量问题。
+- 仓库里存在归档文件、压缩包或嵌套制品，担心 secret 被打包后藏进历史产物。
+- 团队希望为 false positives 建立稳定 baseline，而不是每次都手工重判全部命中。
+
+## 不适用场景
+
+- 仓库本身不承载源码或配置，只是一个运行时消费端，且 secret 只存在于外部密钥系统中。
+- 团队还没有明确 secret 发现后由谁响应、谁负责旋转、谁负责清理历史。
+- 期望 secret 扫描替代密钥管理、权限收敛、发布审计或人工安全 review。
+- 团队无法接受任何形式的误报却又不愿维护 baseline、allowlist 或 triage 流程。
+
+## 推荐落地方式
+
+1. 先明确扫描边界，不要一上来把所有路径都当成阻塞项：
+   - PR 阶段优先扫 diff
+   - 默认分支定期扫全仓库
+   - 发现历史问题时再单独跑历史扫描和清理
+2. 第一轮先建立 baseline，再谈门禁：
+   - 把已知存量命中固化成 baseline 或忽略列表
+   - 只对新增命中、严重命中或高可信命中设置阻塞
+   - 给每条 baseline 记录 owner、原因和到期复核时间
+3. 将 secret scanning 与现有安全链分层：
+   - `dependency-review-gates` 负责依赖和许可证变化
+   - `codeql-pr-security-gates` 负责代码级语义问题
+   - `trivy-security-gates` 负责镜像、文件系统和 IaC 中的 secret / misconfiguration
+   - `secret-scanning-gates` 负责源码仓库、PR diff 与历史中的硬编码 secret
+   - 安全评审角色、`/team-review` 负责最终判断与阻塞决策
+4. 命中后不要只“报出来”：
+   - 先确认命中是否为真实 secret
+   - 再判断是否需要立刻 rotate、revoke 或 purge 历史
+   - 需要时把清理、替换和复查拆成独立任务
+5. 结果必须回写到 PR、review 结论或发布记录，不要只停在扫描输出里。
+
+## 最小门禁模型
+
+- `target layer`：源码、配置、脚本、文档、测试数据和归档文件
+- `scan layer`：gitleaks 对当前内容、diff 或历史做 secret 检测
+- `baseline layer`：已知存量命中、误报和临时豁免
+- `triage layer`：确认命中是否真实、是否新增、是否阻塞
+- `decision layer`：安全评审角色、`tech-lead`、`devops-engineer` 决定是否放行
+
+重点不是“有没有命中”，而是这条命中是否是新增、是否是真 secret、是否已经被接管处理。
+
+## 重点检查项
+
+- 是否出现硬编码 token、API key、密码、私钥、访问凭证或 session 信息
+- 是否把真实 secret 写进示例、测试数据、文档或脚本中
+- 是否在归档文件、压缩包或嵌套制品里藏入了 secret
+- 是否只是旧 baseline 复现，还是本次变更引入的新问题
+- 是否存在高置信规则命中，但还需要人工确认上下文才能判断是否真漏
+- 是否有重复出现的 secret 类型，说明仓库里存在系统性泄漏模式
+
+## 反模式
+
+- 只看扫描结果条数，不区分真实命中、误报和存量 baseline。
+- 因为误报多就直接关闭 secret 扫描，最后让真正泄漏无人发现。
+- 命中以后只删代码，不做 token 轮换、访问撤销或历史清理。
+- 只扫 PR diff，不扫默认分支和历史，导致旧 secret 一直留在仓库里。
+- baseline 永久不复核，最后把所有问题都变成“已知问题”。
+
+## 输出回落
+
+- PR 阶段：把新增命中、误报判断和 triage 结论写入 review 摘要。
+- 评审阶段：在 `/team-review` 中明确哪些命中来自 secret scanning，哪些已被人工确认、豁免或阻塞。
+- 发布阶段：若仍存在未关闭的高风险命中，必须回写到 `/team-release` 的风险、放行结论或后续观察项。
+- 事故处理：若确认泄漏，必须同步到 token 轮换、密钥撤销、历史清理和复查任务。
+
+## 许可证与使用边界
+
+- `gitleaks/gitleaks` 采用 MIT License。
+- 启用前应确认仓库扫描范围、baseline 管理方式、误报 triage 责任人和 secret 轮换流程。
+- 对组织级仓库、历史扫描和高敏感仓库，建议先用非阻塞模式观察一轮，再逐步收紧门禁。
+
+## 参考来源
+
+- [gitleaks/gitleaks](https://github.com/gitleaks/gitleaks)
+- [gitleaks/gitleaks-action](https://github.com/gitleaks/gitleaks-action)

package/docs/runbooks/security-compliance-platform-demo-execution-log.md

@@ -0,0 +1,36 @@
+---
+version: "0.1.0"
+status: draft
+created: 2026-03-29
+updated: 2026-03-29
+owner: 工程团队
+---
+
+# 安全与合规平台演示执行记录
+
+本文记录一条安全 / 合规平台演示路径，重点展示团队如何把门禁、例外、审计证据和放行条件整理成正式治理链路。
+
+## 1. 场景定义
+
+- 背景：仓库已具备多种安全门禁，但缺少统一的分层结论与放行规则
+- 目标：把安全结论从“工具输出”升级成“可 review、可 release、可审计”的治理结果
+
+## 2. 关键阶段
+
+- `/team-intake`：锁定门禁范围、权限边界和放行条件
+- `/team-plan`：拆风险分层、例外管理和 release 记录
+- `/tdd`：先定义阻塞项、例外项、观察项
+- `/verify`：汇总门禁结果与审计证据
+- `/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/security-compliance-platform-demo-script.md

@@ -0,0 +1,49 @@
+---
+version: "0.1.0"
+status: draft
+created: 2026-03-29
+updated: 2026-03-29
+owner: 工程团队
+---
+
+# 安全与合规平台演示剧本
+
+本文是一份可直接照着讲的演示脚本，面向安全门禁、权限治理、审计证据和放行规则场景。
+
+## 1. 演示目标
+
+- 说明阻塞项、例外项、观察项必须分层
+- 说明 `/tdd` 如何前置锁定放行标准
+- 说明 `/verify` 如何把门禁结果转成 review / release 结论
+
+## 2. 演示脚本
+
+### Step 1. 先讲风险分层
+
+```text
+安全治理最大的误区不是工具不够，而是把阻塞项、例外项和观察项混成一个结论。
+```
+
+### Step 2. 用 `/team-intake` 锁目标
+
+```text
+/team-intake
+目标：补齐安全基线与合规审计仓库的门禁、证据和放行规则
+范围：安全扫描、权限基线、例外管理、release 说明、测试计划
+不做：无关业务功能改造
+约束：必须区分阻塞风险、可接受例外、观察项和最终放行条件
+```
+
+### Step 3. 用 `/tdd` 锁放行标准
+
+```text
+/tdd
+基于当前 plan 结果，先定义阻塞项、可接受例外、观察项、审计证据和最终放行条件。
+```
+
+### Step 4. 用 `/verify` 收口
+
+```text
+/verify
+请基于当前安全改动，输出门禁结果、权限风险、例外项、证据留存和可直接进入 /team-review 或 /team-release 的结论。
+```

package/docs/runbooks/security-compliance-platform-walkthrough.md

@@ -0,0 +1,98 @@
+---
+version: "0.1.0"
+status: draft
+created: 2026-03-29
+updated: 2026-03-29
+owner: 工程团队
+---
+
+# 安全与合规平台演练
+
+本文演示一个以安全门禁、权限治理、审计证据和放行规则为核心的仓库，如何从风险澄清到 review / release 收口完整跑通。
+
+## 1. 场景
+
+- 仓库当前主要维护安全扫描、权限基线、例外管理和审计记录
+- 团队准备补齐安全门禁与发布放行规则
+- 目标不是改业务功能，而是把安全结论治理成可分层解释、可复盘、可放行的状态
+
+## 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
+目标：补齐安全基线与合规审计仓库的门禁、证据和放行规则
+范围：安全扫描、权限基线、例外管理、release 说明、测试计划
+不做：无关业务功能改造
+约束：必须区分阻塞风险、可接受例外、观察项和最终放行条件
+```
+
+### 期望输出重点
+
+- 识别这是安全治理任务，而不是普通交付任务
+- 明确参与角色至少包括 `tech-lead`、`architect`、`qa-engineer`、`devops-engineer`
+- 风险应聚焦权限边界、审计缺口、放行标准不清和例外项失控
+
+## 4. 第二步：/team-plan
+
+### 需要拆清的动作
+
+- 安全门禁与风险分层
+- 权限边界与例外管理
+- 审计证据和 release 记录
+- review / release 中的接受风险位置
+
+## 5. 第三步：/tdd
+
+重点是先锁风险分层和放行标准：
+
+- 哪些是阻塞项
+- 哪些是可接受例外
+- 哪些只是观察项
+- 哪些证据必须进入 review / release
+
+## 6. 第四步：/team-execute
+
+执行阶段通常包含：
+
+- 调整扫描与基线规则
+- 收敛权限与例外说明
+- 更新 review / release 模板与证据位置
+
+## 7. 第五步：/verify
+
+Verify 阶段要回答：
+
+- 当前阻塞项有哪些
+- 例外项是否有正式接受记录
+- 审计证据是否可追溯
+- 当前是否满足进入 review / release 的条件
+
+## 8. 第六步：/team-review 与 /team-release
+
+### Review 阶段要回答
+
+- 当前是否还存在阻塞发布的安全风险
+- 哪些例外暂时接受，谁负责承担
+
+### Release 阶段要回答
+
+- 放行条件是什么
+- 回退或临时降级路径是什么
+
+## 9. 常见错误
+
+- 把阻塞项和观察项混成一个结论
+- 工具通过了，但没有正式放行说明
+- 例外项没有责任人和期限

package/docs/runbooks/slsa-generator-patterns.md

@@ -0,0 +1,73 @@
+# SLSA Generator 模式手册
+
+本手册承接 `slsa-framework/slsa-github-generator` 的工程实践，用于把 GitHub Actions 侧的 provenance 生成模式纳入供应链治理链。它补的是“如何把构建来源、工作流和产物绑定成可追溯证据”这一层，不替代 `artifact-attestation-gates`、`slsa-verification-gates`、`cosign-signing-gates` 或人工放行判断。
+
+## 适用场景
+
+- 仓库的正式构建和发布已经主要运行在 GitHub Actions 上。
+- 团队希望为 release artifact、镜像或构建产物生成 provenance / attestation，并让后续验证有稳定输入。
+- 需要把 workflow、runner、commit、subject digest 和发布产物串成一条可审计的证据链。
+- 希望先补“生成模式”和“证据结构”，再决定是否上更强的验证或策略强制。
+
+## 不适用场景
+
+- 当前还没有稳定的 GitHub Actions 构建链，却为了形式完整性强行引入 provenance 生成。
+- 团队还没定好产物命名、归档位置或 release 记录结构。
+- 期望这个手册替代 SBOM、签名、验证或集群侧强制策略。
+- 仓库主要不在 GitHub Actions 上构建，或者生成链条无法稳定拿到 subject 和 workflow 信息。
+
+## 推荐落地方式
+
+1. 先把 provenance 生成限定在少数正式制品，不要一开始覆盖所有 job。
+2. 第一阶段先固定三件事：
+   - 哪些产物需要生成 provenance
+   - provenance 依赖哪些 workflow 元数据
+   - 生成结果存放在哪里、谁来回链
+3. 将生成模式与现有链路分层：
+   - `sbom-generation-gates` 负责成分清单
+   - `artifact-attestation-gates` 负责构建来源证明
+   - `slsa-generator-patterns` 负责 GitHub Actions 侧的生成模式与 workflow 约束
+   - `slsa-verification-gates` 负责独立验证 provenance / attestation
+4. 先从“单 workflow、单产物、单发布路径”开始，再逐步扩展到多 job 或多制品。
+5. 结果必须回写到 `/team-release`、发布记录或制品元数据中，不让 provenance 只停在 Actions 运行日志里。
+
+## 最小门禁模型
+
+- `source layer`：源码仓库、commit、tag 或 release 触发点
+- `workflow layer`：GitHub Actions workflow、job、runner、permissions
+- `provenance layer`：subject、digest、构建输入和生成结果
+- `decision layer`：`devops-engineer`、`tech-lead` 判断生成结果是否满足发布要求
+
+重点不是“装了一个 action”，而是生成出来的证据能稳定对应到实际发布产物。
+
+## 重点检查项
+
+- workflow 是否明确生成对象，而不是把 provenance 当成附带副作用
+- subject、digest 和 release artifact 是否一一对应
+- workflow permissions、runner 选择和产物上传路径是否稳定可审计
+- 生成结果是否有固定命名、归档位置和 release 回链方式
+- 后续验证链是否能直接消费当前生成格式，而不是再做一次临时转换
+
+## 反模式
+
+- 只在某个 job 里“顺手生成” provenance，却没定义它对应哪个正式产物。
+- workflow 里没有固定 subject 或 digest，导致每次生成出来的证据都不稳定。
+- 生成结果只保存在 Actions summary，没有进入发布记录或审计链。
+- 还没跑通归档和验证链，就先把 provenance 生成当成最终门禁。
+
+## 输出回落
+
+- 构建阶段：记录哪些正式制品生成了 provenance、workflow 信息和 subject 绑定关系。
+- 发布阶段：把 provenance 文件、URL 或摘要写入 `/team-release` 的检查结果、发布方案或放行结论。
+- 审计阶段：若需要追溯某次发布，必须能从 release 记录定位到 provenance，并反查到对应 workflow 和 commit。
+
+## 许可证与使用边界
+
+- `slsa-framework/slsa-github-generator` 采用 Apache-2.0。
+- 启用前应确认仓库主要构建平台、GitHub Actions 权限、产物发布位置和团队是否能维护 provenance 归档。
+
+## 参考来源
+
+- [slsa-framework/slsa-github-generator](https://github.com/slsa-framework/slsa-github-generator)
+- [artifact-attestation-gates.md](artifact-attestation-gates.md)
+- [slsa-verification-gates.md](slsa-verification-gates.md)