@colin4k1024/tsp 2.4.5 → 2.4.7

package/docs/runbooks/github-actions-supply-chain-walkthrough.md

@@ -1,117 +0,0 @@
----
-version: "0.1.0"
-status: draft
-created: 2026-03-29
-updated: 2026-03-29
-owner: 工程团队
----
-
-# GitHub Actions 与供应链治理演练
-
-本文演示一个以 GitHub Actions、权限治理和供应链门禁为核心的仓库，如何从治理目标拆解到 workflow 调整、证据链回写和发布收口。
-
-## 1. 场景
-
-- 仓库当前使用 GitHub Actions 承担构建、测试、发布
-- 团队准备补齐 actionlint、scorecard、token 权限、SBOM、attestation 和签名链路
-- 目标不是改业务代码，而是把 workflow 与供应链基线治理成可审计状态
-
-## 2. 推荐链路
-
-1. `/team-intake`
-2. `/team-plan`
-3. `/tdd`
-4. `/team-execute`
-5. `/harness-audit`
-6. `/team-review`
-7. `/team-release`
-
-## 3. 第一步：/team-intake
-
-### 输入示例
-
-```text
-/team-intake
-目标：重构 GitHub Actions 发布链路并补齐供应链门禁
-范围：workflow、permissions、attestation、SBOM、签名、review 说明
-不做：业务服务代码改造
-约束：必须区分 actionlint、scorecard、token 权限、SLSA 和 artifact attestation 的边界
-```
-
-### 期望输出重点
-
-- 识别这是平台治理 / 供应链治理任务，而不是业务功能任务
-- 明确参与角色至少包括 `tech-lead`、`architect`、`qa-engineer`、`devops-engineer`
-- 风险应聚焦 workflow 误配、权限过宽、证据链缺失和发布不可追溯
-
-## 4. 第二步：/team-plan
-
-### 需要拆清的动作
-
-- workflow 结构调整
-- token 权限收敛
-- actionlint / scorecard / zizmor 等门禁的分层接入
-- SBOM、attestation、签名、SLSA 的发布证据链回写
-- handoff、review 和 release 中的治理记录位置
-
-### 合格输出应该回答
-
-1. 哪些 workflow 调整是结构问题
-2. 哪些是权限问题
-3. 哪些是供应链证据问题
-4. 最终如何进入 `/team-review` 和 `/team-release`
-
-## 5. 第三步：/tdd
-
-在这类仓库里，`/tdd` 重点不是业务测试，而是先锁完成标准：
-
-- workflow lint、权限治理和 attestation 的边界是否说清
-- 哪些证据必须进入 review 结果
-- 哪些证据必须进入 release 记录
-- validate / build / release 链路是否有清晰回退路径
-
-## 6. 第四步：/team-execute
-
-执行阶段通常包含：
-
-- 调整 workflow YAML
-- 收紧 job 级 `permissions`
-- 接入 actionlint、scorecard、token 权限基线、SLSA 或 attestation
-- 更新 runbook、review 说明和 release 检查项
-
-本阶段输出至少应包含：
-
-- workflow 变更摘要
-- 影响范围
-- 校验结果
-- 剩余风险和例外项
-
-## 7. 第五步：/harness-audit
-
-这里的 audit 重点不是业务功能，而是平台入口和治理链是否同步：
-
-- 新增 workflow 治理要求是否进入 runbook
-- review/release 是否已经能承接供应链证据
-- examples、quick start 或 usage 文档是否需要补入口
-
-## 8. 第六步：/team-review 与 /team-release
-
-### Review 阶段要回答
-
-- 当前有哪些阻塞的 workflow 或权限风险
-- 哪些例外可以暂时接受
-- 哪些供应链门禁已形成证据链
-
-### Release 阶段要回答
-
-- 哪些 artifact 会生成 SBOM / attestation / 签名
-- 哪些 workflow、runner、commit 和 digest 需要被记录
-- 出现发布异常时如何快速回退到上一套 workflow / 发布配置
-
-## 9. 常见错误
-
-- 把 actionlint、scorecard、permissions、SLSA 混成同一层结论
-- 只改 workflow，不回写 review 或 release 结论
-- 生成了 attestation 或 SBOM，但没有放到可追溯位置
-
-建议配合阅读：[actionlint-workflow-gates.md](actionlint-workflow-gates.md)、[scorecard-supply-chain-gates.md](scorecard-supply-chain-gates.md)、[github-token-permissions-baseline.md](github-token-permissions-baseline.md)、[artifact-attestation-gates.md](artifact-attestation-gates.md)、[slsa-generator-patterns.md](slsa-generator-patterns.md)

package/docs/runbooks/github-token-permissions-baseline.md

@@ -1,92 +0,0 @@
-# GitHub Token 权限基线手册
-
-本手册承接 `GitHubSecurityLab/actions-permissions` 的工程实践，用于把 GitHub Actions 中 `GITHUB_TOKEN` 的真实使用情况转成最小权限建议，并把这些建议回落到 PR 评审、workflow 调整和治理记录里。它补的是“这个 workflow 运行时到底用了哪些 token 权限、哪些权限可以收窄”这一层，不替代 `scorecard-supply-chain-gates`、`zizmor-workflow-audits`、`runner-egress-hardening`、`actionlint` 或人工 review。
-
-## 用途 / 定位
-
-- 这个 runbook 面向 GitHub Actions 的 token 权限收敛，核心对象是 `GITHUB_TOKEN`、workflow/job 级 `permissions` 配置和默认工作流权限。
-- 它基于真实 workflow run 的活动来给出最小权限建议，适合用来验证“理论上可能需要”和“实际运行中确实需要”之间的差异。
-- 它不是仓库级供应链总审计，也不是 workflow 语法审计，更不是 runner 网络出口控制。
-
-## 适用场景
-
-- 仓库已经大量使用 GitHub Actions，但 `permissions` 仍然依赖默认值，或者长期保持过宽的 `write` 权限。
-- 团队想把“最小权限”从经验判断升级成可观察、可回放、可 triage 的证据链。
-- 某些 workflow 只有在部分分支、条件分支、skip 条件或少数 job 下才会触发，单次检查很难完整覆盖权限需求。
-- 团队希望在收紧 `GITHUB_TOKEN` 前先做一轮观察，避免直接改配置导致 workflow 失效。
-
-## 不适用场景
-
-- 仓库没有使用 GitHub Actions，或者 token 权限主要由外部系统控制，与当前仓库的 workflow 无关。
-- 你要查的是 YAML 结构、表达式注入、危险 `uses:`、secret 泄露或 shell 误用，而不是 token 权限本身。
-- 你要管的是 runner 的出站网络、DNS、镜像仓库访问或外部 API 连接，而不是 GitHub token scope。
-- 团队已经有稳定、明确且经过验证的 `permissions` 基线，只需要做一次性文档归档。
-
-## 推荐落地方式
-
-1. 先把 `actions-permissions` 当成“观察和建议层”，不要一开始就把它当硬阻塞门禁。
-2. 对关键 workflow 的每个 job 先观察真实运行，再汇总最小权限建议；官方仓库说明里明确提到，`Monitor` 会根据实际检测到的 workflow 活动给出建议，而 `Advisor` 可以汇总多次运行结果。
-3. 优先覆盖构建、发布、制品上传、PR 处理、标签/分支管理和其他会直接碰仓库状态的 job。
-4. 收敛顺序建议是：
-   - 先明确 workflow 或 job 的默认权限来源
-   - 再补上显式 `permissions`
-   - 再按 job 细化到只保留实际需要的 scope
-   - 最后移除临时观察用的 `Monitor`
-5. 将结果与现有链路分层：
-   - `scorecard-supply-chain-gates` 负责仓库级供应链基线、token 默认策略、action pinning 和治理面
-   - `zizmor-workflow-audits` 负责 workflow 安全审计细节，例如危险表达式、`uses:` 风险和可疑结构
-   - `runner-egress-hardening` 负责 runner 运行时出站访问控制与监测
-   - 本手册负责把“实际用了什么权限”转成可执行的最小权限建议
-6. 若建议权限与现有 workflow 行为冲突，先做人工 triage，不要直接把所有建议都自动升级为阻塞项。
-
-## 最小门禁模型
-
-- `observation layer`：在 job 运行中记录 `GITHUB_TOKEN` 实际触发到的仓库操作。
-- `recommendation layer`：把单次或多次运行的观察结果聚合为最小权限建议。
-- `permission layer`：将建议固化到 workflow/job 级 `permissions`，并与默认权限策略对齐。
-- `decision layer`：`code-review`、`team-review`、`tech-lead` 和必要的安全角色决定是否接受、例外放行或继续收敛。
-
-重点不是“工具说应该给多少”，而是“当前 workflow 证据链是否足以支撑这个最小权限配置”。
-
-## 重点检查项
-
-- 默认工作流权限是否过宽，是否应该从 `write` 收敛到 `read` 或更细粒度的 job 级配置。
-- workflow 或 action 是否在未显式传参的情况下仍会通过 `github.token` 访问 `GITHUB_TOKEN`。
-- 是否存在只在少数分支、条件分支、skip 分支或部分 job 中才出现的权限需求，导致单次观察不完整。
-- 是否把 `issues: write`、`pull-requests: write`、`contents: write`、`packages: write` 等权限保留成了习惯性默认值。
-- 是否需要 GitHub Actions 提交 approving PR review；官方 REST 能力本身就把这项能力单独暴露出来，说明它应当被视为单独的治理项，而不是顺手打开。
-- 观察结论是否和最终 workflow 配置一致，避免“工具建议已经收敛，但 YAML 里仍然是宽权限”。
-
-## 反模式
-
-- 只跑一次 Monitor 就立刻定版，忽略了条件分支、跳过 job 和不同触发路径。
-- 把 Advisor 的汇总结果当成绝对真理，不做人工 triage。
-- 看到某个 job 需要高权限，就把整个 workflow 统一放大到同等权限。
-- 只改仓库默认权限，不补 job 级 `permissions`，最后让默认值继续漂移。
-- 把这个工具拿去替代 `scorecard`、`zizmor` 或 `runner-egress-hardening`，结果把不同层的问题混在一起处理。
-- 只把建议留在 action 产物里，没有回写到 review、治理记录或 workflow 文件。
-
-## 输出回落
-
-- PR 阶段：把 Monitor/Advisor 的结论、最终 permissions 变更和仍需例外说明的 scope 写入 review 摘要。
-- 评审阶段：在 `/team-review` 中明确当前 workflow 的最小权限基线、临时放宽原因和后续收敛计划。
-- 发布阶段：若某个发布 job 仍需要较高权限，必须说明它对应的仓库操作范围和回退边界。
-- 治理阶段：把长期存在的权限例外、默认值调整和 workflow 重构计划沉淀到 ADR 或 runbook。
-
-## 许可证与使用边界
-
-- `GitHubSecurityLab/actions-permissions` 在官方仓库中标注为 MIT license，且当前仓库主页明确把它定位为 `Monitor` 和 `Advisor` 两个 GitHub token permissions action。
-- 官方仓库同时标注为 `PUBLIC BETA`，因此接入前要接受它可能带来的误报、覆盖缺口和维护成本。
-- GitHub 官方文档说明，`GITHUB_TOKEN` 具有仓库范围限制，workflow 可以通过 `permissions` 精确控制 `read`、`write` 或 `none`，而且默认工作流权限与是否允许 Actions 提交 approving PR review 都是可单独治理的设置。
-- 使用前要确认你对目标仓库拥有足够的 GitHub Actions 配置权限，因为相关 REST API 本身就区分组织级和仓库级管理权限。
-
-## 参考来源
-
-- [GitHubSecurityLab/actions-permissions](https://github.com/GitHubSecurityLab/actions-permissions)
-- [GitHub Docs: GITHUB_TOKEN](https://docs.github.com/en/actions/concepts/security/github_token)
-- [GitHub Docs: Use GITHUB_TOKEN in workflows](https://docs.github.com/en/actions/how-tos/writing-workflows/choosing-what-your-workflow-does/controlling-permissions-for-github_token)
-- [GitHub Docs: Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions)
-- [GitHub Docs: REST API endpoints for GitHub Actions permissions](https://docs.github.com/en/rest/actions/permissions)
-- [scorecard-supply-chain-gates.md](scorecard-supply-chain-gates.md)
-- [zizmor-workflow-audits.md](zizmor-workflow-audits.md)
-- [runner-egress-hardening.md](runner-egress-hardening.md)

package/docs/runbooks/gitlab-manual-pipeline-release.md

@@ -1,5 +0,0 @@
-# GitLab Manual Pipeline Release
-
-该企业 GitLab 发布 runbook 已迁移到私有 `enterprise` overlay 仓库。公开仓不再内置企业发布流程手册。
-
-公开安装与 overlay 约定见 [custom-overlay.md](custom-overlay.md)。

package/docs/runbooks/gitlab-release-integration-playbook.md

@@ -1,5 +0,0 @@
-# GitLab Release Integration Playbook
-
-该企业发布集成 playbook 已迁移到私有 `enterprise` overlay 仓库。公开仓仅保留兼容入口。
-
-公开安装与 overlay 约定见 [custom-overlay.md](custom-overlay.md)。

package/docs/runbooks/gitnexus-code-intelligence-usage.md

@@ -1,133 +0,0 @@
----
-version: "0.1.0"
-status: active
-created: 2026-05-05
-updated: 2026-05-05
-owner: 工程团队
-doc_tier: runbook
-last_verified: 2026-05-05
-source_of_truth:
-  - ../../skills/gitnexus/SKILL.md
-  - ../../README.md
-  - ../../AGENTS.md
-  - https://github.com/abhigyanpatwari/GitNexus
----
-
-# GitNexus 代码智能能力使用手册
-
-## 1. 定位
-
-GitNexus 在 TSP 中是 **受控可选代码智能能力**。它适合 brownfield 存量系统的 MCP 查询、影响面分析、`detect_changes`、多仓分析和更深代码图谱证据。
-
-它不替代 `/team-*` 主链，也不替代 `/update-codemaps` 的轻量现状快照。Graphify 继续用于轻量结构证据；GitNexus 用于需要 MCP tool、symbol impact、git diff impact 或多仓上下文的场景。
-
-## 2. 前置检查
-
-先跑：
-
-```bash
-npm run gitnexus:doctor
-```
-
-检查项：
-
-- Node 版本 `>= 20`
-- `npm` / `npx` 可用
-- npm 上游包元数据可读取时，展示 GitNexus 版本、许可证与 engine 要求
-
-如果 npm registry 临时不可用，脚本只给 warning，不会自动安装任何依赖。
-
-## 3. 许可证与边界
-
-截至本手册核对日期，GitNexus npm 元数据显示许可证为 `PolyForm-Noncommercial-1.0.0`，Node engine 为 `>=20.0.0`。TSP 本身仍保持 MIT 许可证和 Node `>=18` 基线，因此只做 reference/runbook/thin-skill 集成。
-
-明确边界：
-
-- 不把 GitNexus 加入 TSP `dependencies`
-- 不默认安装 GitNexus
-- 不自动运行 `gitnexus setup`
-- 不复制 GitNexus 源码、hooks、skills 或生成产物
-- 商业使用前由用户自行确认上游授权
-
-## 4. 推荐命令
-
-> 下面是 TSP 的安全推荐入口，具体参数以上游 `gitnexus --help` 为准。
-
-```bash
-# 在目标项目根目录建立或刷新索引，同时保留现有 AGENTS.md / CLAUDE.md 契约
-npx --yes gitnexus@latest analyze --skip-agents-md
-
-# 查看当前项目索引状态
-npx --yes gitnexus@latest status
-
-# 查看已索引仓库
-npx --yes gitnexus@latest list
-
-# 启动 MCP stdio server，供手动配置使用
-npx --yes gitnexus@latest mcp
-```
-
-如果要配置 Codex MCP，优先手动写入项目级或用户级配置，避免自动改写未知编辑器配置：
-
-```toml
-[mcp_servers.gitnexus]
-command = "npx"
-args = ["--yes", "gitnexus@latest", "mcp"]
-```
-
-## 5. 与主链结合方式
-
-### 5.1 `/team-plan` 前的 brownfield 深分析
-
-推荐路径：
-
-1. `/team-help` 判断当前阶段
-2. `/update-codemaps` 生成轻量现状快照
-3. 需要跨模块影响面或 MCP 证据时，执行 GitNexus 索引与查询
-4. `/team-plan` 消费 GitNexus 发现，完成 Brownfield Context Snapshot、challenge/design/readiness 收口
-
-### 5.2 `/team-execute` 阶段的影响面确认
-
-- 对 story slice 的关键 symbol、API 或 handler 做 impact/context 查询
-- 对准备提交的 diff 做 detect_changes 类分析
-- 将结果写入执行日志或 handoff，避免“代码已改但影响未知”
-
-### 5.3 `/team-review` 阶段的证据落盘
-
-评审结论至少记录：
-
-- 本次分析目标
-- 使用的 GitNexus 入口（MCP tool/resource 或 CLI 命令）
-- 关键影响面
-- 风险等级或剩余疑点
-- 对回归测试、发布或回滚的影响
-
-## 6. Artifact / Handoff 摘要格式
-
-建议在 `docs/artifacts/{date}-{slug}/delivery-plan.md`、`arch-design.md`、handoff 或 review 记录中使用这个最小格式：
-
-```markdown
-## GitNexus Evidence
-
-- Goal: [本次要确认的问题]
-- Entry: [MCP tool/resource 或 CLI 命令]
-- Findings: [关键调用链、依赖、影响面]
-- Decision impact: [改变了哪个计划、测试或发布判断]
-- Follow-up: [仍需验证或暂缓的事项]
-```
-
-## 7. 禁用项
-
-- 不自动运行 `gitnexus setup`
-- 不运行会覆盖 TSP 管理入口文档的索引命令
-- 不把 `.gitnexus/` 数据库当作 TSP artifact 提交
-- 不用 GitNexus 结论绕过 `/team-plan`、`/team-review` 或验证门禁
-
-## 8. 与 Graphify 的分工
-
-| 能力 | 默认用途 |
-|------|----------|
-| Graphify | 轻量结构扫描、依赖路径、架构问答证据 |
-| GitNexus | MCP 查询、symbol impact、detect_changes、多仓和执行流证据 |
-
-默认先保留 `/update-codemaps` 作为 brownfield 快照入口；图谱工具只在问题需要更强结构证据时启用。

package/docs/runbooks/graphify-knowledge-graph-usage.md

@@ -1,88 +0,0 @@
----
-version: "0.1.0"
-status: active
-created: 2026-04-17
-updated: 2026-04-17
-owner: 工程团队
-doc_tier: runbook
-last_verified: 2026-04-17
-source_of_truth:
-  - ../../skills/graphify/SKILL.md
-  - ../../README.md
-  - ../../AGENTS.md
----
-
-# Graphify 知识图谱能力使用手册
-
-## 1. 定位
-
-Graphify 在本仓库的定位是 **可选知识图谱能力**，用于补齐 brownfield 结构认知、架构问答和依赖影响分析。  
-它不会替代当前 workflow-engine，也不会改变 `/team-*` 主链职责。
-
-## 2. 前置检查
-
-先跑：
-
-```bash
-npm run graphify:doctor
-```
-
-检查项：
-
-- Python 版本 `>= 3.10`
-- `graphify` CLI 可用（对应 Python 包 `graphifyy`）
-
-如果失败，按脚本提示在你的本地环境修复。仓库不自动安装 Python 或 `graphifyy`。
-
-## 3. 推荐命令（以上游 CLI 帮助为准）
-
-> 下面是仓库推荐入口，具体参数以 `graphify --help` 为准。
-
-```bash
-# 1) 构建图谱（统一输出目录）
-graphify build ... --out graphify-out
-
-# 2) 图谱查询（模块/符号/关系）
-graphify query ...
-
-# 3) 依赖路径分析（from -> to）
-graphify path ...
-
-# 4) 解释输出（可读化摘要）
-graphify explain ...
-```
-
-## 4. 与主链结合方式
-
-### 4.1 `/team-plan` 前的 brownfield 扫描
-
-推荐路径：
-
-1. `/team-help` 判定阶段
-2. Graphify 构建图谱 + 关键 query/path
-3. `/team-plan` 消费结构证据，完成 challenge/design/readiness 收口
-
-### 4.2 `/team-execute` 阶段的影响面分析
-
-- 对每个 story slice 变更点做 path/explain，确认上下游影响
-- 结果写入执行日志和 handoff，避免“修改完成但影响未知”
-
-### 4.3 `/team-review` 阶段的证据落盘
-
-- 将图谱结论回写 `docs/artifacts/`、`docs/adr/`、`docs/memory/`
-- 评审时引用“命令 -> 结果 -> 决策影响”三段证据链
-
-## 5. 输出约定
-
-- 统一目录：`graphify-out/`
-- 最小内容：
-  - 分析目标
-  - 关键命令与结果摘要
-  - 对主链决策的影响
-
-## 6. 明确禁用项
-
-- 不在本仓库执行：
-  - `graphify codex install`
-  - `graphify claude install`
-- 原因：避免改写现有 `AGENTS.md` / hooks 契约，破坏当前治理链路。

package/docs/runbooks/handoff-filling-guide-with-examples.md

@@ -1,70 +0,0 @@
----
-version: "0.1.0"
-status: draft
-created: 2026-03-28
-updated: 2026-03-28
-owner: 工程团队
----
-
-# Handoff 填充指南与示例
-
-本文说明 `/handoff` 到底应该交付什么，以及前端、后端和跨角色场景下的 handoff 应该怎样写才够用。
-
-## 1. handoff 的目标
-
-handoff 不是重复 diff，而是让下一角色能直接接住结果。
-
-至少应回答：
-
-- 改了什么
-- 验证了什么
-- 还剩什么风险
-- 下一角色要关注什么
-
-## 2. 最小字段
-
-- 代码变更摘要
-- 自测范围与证据
-- 剩余风险
-- QA 关注点
-- 若命中 custom overlay，则补装配或执行记录
-
-## 3. 后端 API 示例
-
-```text
-代码变更摘要：新增审批记录查询接口，支持分页、状态筛选和权限校验
-自测范围：单测通过，集成测试覆盖正常、无权限和空结果场景
-剩余风险：历史状态枚举兼容性待联调确认
-QA 关注点：极端分页参数、无权限访问、错误码一致性
-```
-
-## 4. 前端页面示例
-
-```text
-代码变更摘要：新增审批记录列表页与筛选表单
-自测范围：已验证桌面、iPad、移动端布局和空态/错误态
-剩余风险：极长审批标题场景待真实数据验证
-QA 关注点：断点切换、键盘可达性、无结果空态
-```
-
-## 5. 跨角色示例
-
-如果一次交接同时包含前后端结果，建议分块写，不要混成一段模糊总结。
-
-## 6. custom overlay 场景
-
-如果启用了 custom overlay，handoff 里还应写：
-
-- 启用了什么能力
-- 为什么启用
-- 做了什么
-- 哪些约束需要 QA 或 release 继续核对
-
-## 7. 常见错误
-
-- 只有“已完成开发”
-- 没有验证证据
-- 没写剩余风险
-- custom overlay 用了却没留下记录
-
-如果你要看 handoff 在完整链路里的位置，继续看 [first-team-workflow-walkthrough.md](first-team-workflow-walkthrough.md)。