@colin4k1024/tsp 2.4.4 → 2.4.6

package/docs/runbooks/troubleshooting.md

@@ -1,234 +0,0 @@
----
-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
-  - ./project-onboarding.md
----
-
-# 安装与使用排障
-
-本文用于排查 Team Skills Platform 在安装、加载和首次使用过程中的高频问题。建议先按症状定位，再看对应章节，而不是从头读到尾。
-
-## 1. 最常见的症状
-
-- 安装脚本执行成功，但看不到 `/team-help`
-- 运行 `node scripts/build-platform-artifacts.js` 或 `node scripts/validate-library.js` 失败
-- Claude 或 Codex 找不到角色 agent / specialist
-- 项目级 `CLAUDE.md` 不知道哪些字段是必须的
-- 使用了 custom overlay，但 review 阶段无法说明启用原因和执行记录
-- `npm run graphify:doctor` 失败（Python 版本或 Graphify CLI 缺失）
-- `npm run gitnexus:doctor` 失败（Node 版本、npm/npx 或许可证确认问题）
-
-## 2. 安装脚本相关问题
-
-### 2.1 构建脚本失败
-
-先检查：
-
-1. 是否在仓库根目录执行脚本
-2. `node` 是否可用
-3. 是否先修改了 canonical source，再执行构建
-
-推荐命令：
-
-```bash
-node scripts/build-platform-artifacts.js
-node scripts/validate-library.js
-node scripts/validate-doc-freshness.js
-```
-
-如果失败，优先看报错是否属于：
-
-- Node.js 版本或环境问题
-- 文档链接失效
-- 生成产物与源文件不一致
-
-### 2.2 安装目录不对
-
-Claude 检查点：
-
-- `~/.claude/commands/team-help.md`
-- `~/.claude/agents/roles/tech-lead.md`
-- `~/.claude/examples/project-CLAUDE.md`
-
-Codex 检查点：
-
-- `$CODEX_HOME_DIR/plugins/team-skills-platform/commands/team-help.md`
-- `$CODEX_HOME_DIR/plugins/team-skills-platform/agents/roles/tech-lead.md`
-- `$AGENTS_HOME_DIR/plugins/marketplace.json`
-
-如果路径不对，检查是否错误覆盖了：
-
-- `CLAUDE_HOME_DIR`
-- `CODEX_HOME_DIR`
-- `AGENTS_HOME_DIR`
-
-## 3. 命令或 agent 不可用
-
-### 3.1 看不到 `/team-help`
-
-按顺序检查：
-
-1. 安装目录是否有命令文件
-2. 是否先执行了构建脚本
-3. 是否安装到了你当前实际使用的 Claude / Codex 目录
-
-如果命令文件存在但仍不可用，先重新安装一次平台，再验证目录落点。
-
-### 3.2 看不到角色 agent 或 specialist
-
-检查：
-
-- Claude：`~/.claude/agents/roles/` 和 `~/.claude/agents/specialists/`
-- Codex：`$CODEX_HOME_DIR/plugins/team-skills-platform/agents/roles/` 和 `.../specialists/`
-
-如果目录存在但上下文中没体现，优先回到 quick start 文档确认你是否仍在正确的使用路径上。
-
-## 4. 项目级 CLAUDE 配置问题
-
-### 4.1 最小必填项
-
-项目级 `CLAUDE.md` 至少应包含：
-
-- 项目背景
-- 默认角色链路
-- 默认命令流
-- 项目约束
-
-如果缺少这些内容，模型很难稳定地遵守边界和门禁。
-
-### 4.2 选哪个示例
-
-优先看 [../../examples/INDEX.md](../../examples/INDEX.md)。
-
-快速规则：
-
-- 全栈混合项目：从 [../../examples/project-CLAUDE.md](../../examples/project-CLAUDE.md) 开始
-- 前端主导项目：从 [../../examples/saas-nextjs-CLAUDE.md](../../examples/saas-nextjs-CLAUDE.md) 开始
-- 后端主导项目：从 [../../examples/springboot-service-CLAUDE.md](../../examples/springboot-service-CLAUDE.md) 开始
-- 流程型企业项目：从 [../../examples/workflow-enterprise-CLAUDE.md](../../examples/workflow-enterprise-CLAUDE.md) 开始
-- 平台治理仓库：从 [../../examples/platform-governance-CLAUDE.md](../../examples/platform-governance-CLAUDE.md) 开始
-- 数据看板项目：从 [../../examples/data-analytics-dashboard-CLAUDE.md](../../examples/data-analytics-dashboard-CLAUDE.md) 开始
-- 不理解每一段作用：先看 [project-claude-design-rationale.md](project-claude-design-rationale.md)
-
-## 5. 主链输出质量问题
-
-### 5.1 execute 结果不够结构化
-
-常见错误：
-
-- 只写“已完成开发”
-- 没有自测结果
-- 没有剩余风险
-
-建议对照 [team-command-output-contracts.md](team-command-output-contracts.md) 和 [first-team-workflow-walkthrough.md](first-team-workflow-walkthrough.md) 补齐结构。
-
-### 5.2 handoff 不知道写什么
-
-`/handoff` 的目标不是重复 diff，而是交代：
-
-- 改了什么
-- 验证了什么
-- 还有什么风险
-- 下一角色应该关注什么
-
-如果启用了 custom overlay，还要附带装配或执行记录。
-
-### 5.3 不知道怎么开口才能拿到结构化输出
-
-如果你发现模型总是只给松散建议，而不是主链可用结果，优先看：
-
-- [claude-conversation-prompt-recipes.md](claude-conversation-prompt-recipes.md)
-- [codex-parallel-prompt-recipes.md](codex-parallel-prompt-recipes.md)
-- [team-commands-quick-prompts.md](team-commands-quick-prompts.md)
-
-## 6. Enterprise Overlay 决策问题
-
-### 6.1 什么时候启用
-
-按这个节奏判断：
-
-- intake：识别候选项
-- plan：确认启用或不启用
-- execute / review：若已启用，记录执行与核对结果
-
-### 6.2 常见误区
-
-- 看到审批或权限字样就立刻默认启用 custom overlay
-- intake 没记录候选项，plan 阶段只能凭记忆判断
-- execute 实际用了 custom overlay，但 review 阶段没有证据可回溯
-
-详细判定清单见 [project-onboarding.md](project-onboarding.md)。
-
-如果你卡在“候选项怎么写”或“plan 怎么表达未启用”，直接看 。
-
-如果你已经进入 review 或 release，但不知道 overlay、runbook、toolkit 的执行记录怎么回写，继续看 。
-
-### 6.3 发布治理不知道从哪看起
-
-如果问题发生在发布、灰度、事故或回滚阶段，优先按下面顺序进入：
-
-1. [release-governance-reading-path.md](release-governance-reading-path.md)
-2. [pre-release-checklist.md](pre-release-checklist.md)
-3. [incident-severity-triage-tree.md](incident-severity-triage-tree.md)
-4. [post-rollback-verification-checklist.md](post-rollback-verification-checklist.md)
-
-## 7. 遇到问题时推荐的回退路径
-
-如果你不知道问题属于哪类，按下面顺序排：
-
-1. 先确认构建和校验脚本能通过
-2. 再确认安装目录和命令文件是否存在
-3. 再确认项目级 `CLAUDE.md` 是否完整
-4. 再确认你当前是在 quick start、onboarding 还是 walkthrough 的正确阶段
-
-如果问题仍无法定位，建议把当前症状、执行命令和失败点整理成一个最小问题描述，再回到对应 runbook 定位。
-
-## 8. Graphify 预检查失败
-
-如果你看到下面任一报错：
-
-- Python 版本低于 `3.10`
-- `graphify` 命令不存在
-
-优先按这个顺序处理：
-
-1. 安装或切换到 Python `3.10+`
-2. 在对应环境安装 `graphify`
-3. 重新执行 `npm run graphify:doctor`
-4. 用 `graphify --help` 验证 CLI 已可用
-
-说明：
-
-- 仓库只提供 preflight 检查，不会自动安装 Python 或 Graphify
-- 不要在本仓库执行 `graphify codex install` / `graphify claude install` 改写现有 AGENTS/hooks 契约
-- Graphify 详细用法见 [graphify-knowledge-graph-usage.md](graphify-knowledge-graph-usage.md)
-
-## 9. GitNexus 预检查失败
-
-如果你看到下面任一报错：
-
-- Node 版本低于 `20`
-- `npm` 或 `npx` 不可用
-- npm registry 元数据读取失败
-
-优先按这个顺序处理：
-
-1. 在目标项目环境切换到 Node `20+`
-2. 确认 `npm --version` 与 `npx --version` 可正常执行
-3. 重新执行 `npm run gitnexus:doctor`
-4. 若 registry 临时不可用，手动核对 GitNexus 上游许可证和 engine 后再决定是否启用
-
-说明：
-
-- 仓库只提供 preflight 检查，不会自动安装 GitNexus
-- 不要自动执行 `gitnexus setup` 改写全局 MCP/editor 配置
-- 在 TSP 管理仓库执行索引时，使用 `npx --yes gitnexus@latest analyze --skip-agents-md`
-- GitNexus 详细用法见 [gitnexus-code-intelligence-usage.md](gitnexus-code-intelligence-usage.md)

package/docs/runbooks/vertical-scenario-capability-matrix.md

@@ -1,107 +0,0 @@
----
-version: "0.1.0"
-status: draft
-created: 2026-03-29
-updated: 2026-03-29
-owner: 工程团队
----
-
-# Vertical 场景能力矩阵
-
-这份矩阵用于回答一个问题：当前各 vertical 场景已经补到了哪一层材料，应该从哪一层开始使用。
-
-如果你只想快速选一个讲解入口，先看 [../presentation/vertical-scenario-route-map.md](../presentation/vertical-scenario-route-map.md)。如果你想按项目类型选模板，先看 [../../examples/INDEX.md](../../examples/INDEX.md)。
-
-## 1. 阅读方式
-
-- `模板`：项目级示例，可直接作为项目配置起点
-- `起手句`：项目类型第一句话，来自 starter playbook
-- `连续脚本`：可直接复制的多轮对话脚本
-- `walkthrough`：演练手册，适合 onboarding 与内部训练
-- `demo script`：可直接照着讲的演示话术
-- `execution log`：适合复盘、同步与汇报的台账
-
-## 2. 场景矩阵
-
-| 场景 | 模板 | 起手句 | 连续脚本 | walkthrough | demo script | execution log | 推荐起点 |
-|------|------|--------|----------|-------------|-------------|---------------|----------|
-| GitHub Actions / 供应链治理 | 已具备 | 已具备 | 已具备 | 已具备 | 已具备 | 已具备 | 先看 demo script |
-| AI / Eval 平台 | 已具备 | 已具备 | 已具备 | 已具备 | 已具备 | 已具备 | 先看 demo script |
-| 移动端 / 小程序交付 | 已具备 | 已具备 | 已具备 | 已具备 | 已具备 | 已具备 | 先看 demo script |
-| IaC / Kubernetes 平台仓库 | 已具备 | 已具备 | 已具备 | 已具备 | 已具备 | 已具备 | 先看 demo script |
-| 插件 / 扩展仓库 | 已具备 | 已具备 | 已具备 | 已具备 | 已具备 | 已具备 | 先看 demo script |
-| 数据 / ML pipeline 仓库 | 已具备 | 已具备 | 已具备 | 已具备 | 已具备 | 已具备 | 先看 demo script |
-| 安全 / 合规平台仓库 | 已具备 | 已具备 | 已具备 | 已具备 | 已具备 | 已具备 | 先看 demo script |
-| 内部开发者平台 | 已具备 | 已具备 | 已具备 | 已具备 | 已具备 | 已具备 | 先看 demo script |
-| 数据可观测性 / 质量平台 | 已具备 | 已具备 | 已具备 | 已具备 | 已具备 | 已具备 | 先看 demo script |
-
-## 3. 推荐入口映射
-
-### GitHub Actions / 供应链治理
-
-- 模板：[../../examples/github-actions-supply-chain-CLAUDE.md](../../examples/github-actions-supply-chain-CLAUDE.md)
-- 演练：[github-actions-supply-chain-walkthrough.md](github-actions-supply-chain-walkthrough.md)
-- 演示：[github-actions-supply-chain-demo-script.md](github-actions-supply-chain-demo-script.md)
-- 台账：[github-actions-supply-chain-demo-execution-log.md](github-actions-supply-chain-demo-execution-log.md)
-
-### AI / Eval 平台
-
-- 模板：[../../examples/ai-eval-platform-CLAUDE.md](../../examples/ai-eval-platform-CLAUDE.md)
-- 演练：[ai-eval-platform-walkthrough.md](ai-eval-platform-walkthrough.md)
-- 演示：[ai-eval-platform-demo-script.md](ai-eval-platform-demo-script.md)
-- 台账：[ai-eval-platform-demo-execution-log.md](ai-eval-platform-demo-execution-log.md)
-
-### 移动端 / 小程序交付
-
-- 模板：[../../examples/mobile-miniapp-CLAUDE.md](../../examples/mobile-miniapp-CLAUDE.md)
-- 演练：[mobile-miniapp-delivery-walkthrough.md](mobile-miniapp-delivery-walkthrough.md)
-- 演示：[mobile-miniapp-demo-script.md](mobile-miniapp-demo-script.md)
-- 台账：[mobile-miniapp-demo-execution-log.md](mobile-miniapp-demo-execution-log.md)
-
-### IaC / Kubernetes 平台仓库
-
-- 模板：[../../examples/iac-kubernetes-platform-CLAUDE.md](../../examples/iac-kubernetes-platform-CLAUDE.md)
-- 演练：[iac-kubernetes-platform-walkthrough.md](iac-kubernetes-platform-walkthrough.md)
-- 演示：[iac-kubernetes-platform-demo-script.md](iac-kubernetes-platform-demo-script.md)
-- 台账：[iac-kubernetes-platform-demo-execution-log.md](iac-kubernetes-platform-demo-execution-log.md)
-
-### 插件 / 扩展仓库
-
-- 模板：[../../examples/plugin-extension-platform-CLAUDE.md](../../examples/plugin-extension-platform-CLAUDE.md)
-- 演练：[plugin-extension-platform-walkthrough.md](plugin-extension-platform-walkthrough.md)
-- 演示：[plugin-extension-platform-demo-script.md](plugin-extension-platform-demo-script.md)
-- 台账：[plugin-extension-platform-demo-execution-log.md](plugin-extension-platform-demo-execution-log.md)
-
-### 数据 / ML pipeline 仓库
-
-- 模板：[../../examples/data-ml-pipeline-CLAUDE.md](../../examples/data-ml-pipeline-CLAUDE.md)
-- 演练：[data-ml-pipeline-walkthrough.md](data-ml-pipeline-walkthrough.md)
-- 演示：[data-ml-pipeline-demo-script.md](data-ml-pipeline-demo-script.md)
-- 台账：[data-ml-pipeline-demo-execution-log.md](data-ml-pipeline-demo-execution-log.md)
-
-### 安全 / 合规平台仓库
-
-- 模板：[../../examples/security-compliance-platform-CLAUDE.md](../../examples/security-compliance-platform-CLAUDE.md)
-- 演练：[security-compliance-platform-walkthrough.md](security-compliance-platform-walkthrough.md)
-- 演示：[security-compliance-platform-demo-script.md](security-compliance-platform-demo-script.md)
-- 台账：[security-compliance-platform-demo-execution-log.md](security-compliance-platform-demo-execution-log.md)
-
-### 内部开发者平台
-
-- 模板：[../../examples/internal-developer-platform-CLAUDE.md](../../examples/internal-developer-platform-CLAUDE.md)
-- 演练：[internal-developer-platform-walkthrough.md](internal-developer-platform-walkthrough.md)
-- 演示：[internal-developer-platform-demo-script.md](internal-developer-platform-demo-script.md)
-- 台账：[internal-developer-platform-demo-execution-log.md](internal-developer-platform-demo-execution-log.md)
-
-### 数据可观测性 / 质量平台
-
-- 模板：[../../examples/data-observability-quality-CLAUDE.md](../../examples/data-observability-quality-CLAUDE.md)
-- 演练：[data-observability-quality-walkthrough.md](data-observability-quality-walkthrough.md)
-- 演示：[data-observability-quality-demo-script.md](data-observability-quality-demo-script.md)
-- 台账：[data-observability-quality-demo-execution-log.md](data-observability-quality-demo-execution-log.md)
-
-## 4. 使用建议
-
-1. 如果你是在 onboarding，一个 vertical 先看模板，再看 walkthrough，最后看 demo script。
-2. 如果你是在汇报，直接从 demo script 开始，再补 execution log。
-3. 如果你是在做文档补齐，优先检查矩阵里是否有缺层，而不是只补一个入口。

package/docs/runbooks/witness-policy-gates.md

@@ -1,78 +0,0 @@
-# Witness 证据策略门禁手册
-
-本手册承接 `in-toto/witness` 的工程实践，用于把证据采集、证据封装与策略评估组织成一条可执行的供应链治理链。它补的是“如何基于真实执行证据做更高级的政策判断”这一层，不替代 SBOM、签名、provenance attestation、SLSA verification 或集群侧的 policy controller。
-
-## 适用场景
-
-- 团队已经有签名、attestation 和基础验证链，想进一步把“证据是否足够、证据是否可信、证据是否符合策略”做成可执行门禁。
-- 需要把构建、发布、部署或执行过程中的 evidence 收集起来，再基于这些 evidence 做 policy 判断。
-- 想把“某次运行到底发生了什么”沉淀成可追溯、可回放、可审计的证据链，而不只是单一的签名结果。
-- 需要更精细地把供应链治理从“文件级验证”推进到“证据驱动的策略评估”。
-
-## 不适用场景
-
-- 当前还没有稳定的签名、attestation 或 verification 链，却先引入 witness 风格的证据策略门禁。
-- 团队还没有明确哪些证据要采集、谁来维护 policy、证据失败后怎么 triage。
-- 期望 witness 替代 SBOM、签名、attestation 或 SLSA verification 的基础门禁职责。
-- 团队只想要一个简单的发布检查清单，而不是证据驱动的策略框架。
-
-## 推荐落地方式
-
-1. 先把 witness 看成“证据和策略的编排层”，不要一开始就把它升级成全集群硬门禁。
-2. 第一阶段先固定三件事：
-   - 哪些执行阶段需要采集 evidence
-   - 这些 evidence 以什么形式归档和回链
-   - 哪些 policy 依赖这些 evidence 做判断
-3. 将 witness 与现有链路分层：
-   - `cosign-signing-gates` 负责签名与验签
-   - `artifact-attestation-gates` 负责 provenance attestation
-   - `slsa-verification-gates` 负责独立验证 attestation 是否匹配目标产物
-   - `policy-controller-gates` 负责在集群 admission 层强制执行已确认的策略
-   - witness 负责把 evidence 收集、归档、解释并喂给更上层的 policy decision
-4. 建议先从少量高价值流程试点，比如构建链、发布链或关键部署链，不要一开始就覆盖全部工作负载。
-5. 结果必须回写到 `/team-release`、审计记录或治理文档中，不让 evidence 只停在运行时日志里。
-
-## 最小门禁模型
-
-- `evidence layer`：构建、测试、发布或部署过程中采集到的 evidence
-- `policy layer`：基于 evidence 进行的策略规则和判断条件
-- `evaluation layer`：witness 对 evidence 与 policy 的匹配与评估
-- `decision layer`：`devops-engineer`、`tech-lead` 决定“证据不足”是否阻塞发布或部署
-
-重点不是“收集了一堆日志”，而是这些 evidence 是否能支撑可重复的 policy decision。
-
-## 重点检查项
-
-- evidence 是否来自真实执行链，而不是手工拼接或事后补写
-- policy 是否明确描述了“需要哪些证据、缺什么算失败、如何例外”
-- evidence 与产物、commit、workflow、digest 或环境上下文是否能稳定关联
-- 证据失败时是否有清晰的 triage、回退和例外处理
-- 不同环境或不同阶段的 policy 是否能持续维护，而不是一次配置后长期漂移
-
-## 反模式
-
-- 只收集 evidence，却没有明确 policy，最后变成一堆无法消费的日志。
-- policy 写得过于宽泛，任何结果都能解释成“通过”，失去门禁意义。
-- evidence 只存在于临时目录或终端输出里，没有回链到 release 记录或治理文档。
-- 在没有前置签名、attestation 或 verification 链的情况下，直接把 witness 当成最终阻塞点。
-- 证据失败后没人负责 triage，最后团队把 policy gate 当成噪音源。
-
-## 输出回落
-
-- 构建阶段：记录关键执行步骤产生的 evidence、归档位置和可回放方式。
-- 发布阶段：把 witness 评估结果、失败摘要或例外结论写入 `/team-release` 的检查结果或放行结论。
-- 审计阶段：若后续要追溯某次发布或部署，必须能从 release 记录定位到对应 evidence，再反查到 policy 决策。
-
-## 许可证与使用边界
-
-- `in-toto/witness` 采用 Apache-2.0。
-- 启用前应确认 evidence 采集范围、policy 维护责任、运行环境和团队是否有能力长期维护规则。
-- 如果团队当前还处在“先补 SBOM / 签名 / attestation / verification”的阶段，witness 应该先作为参考型治理层，而不是立刻成为强阻塞门禁。
-
-## 参考来源
-
-- [in-toto/witness](https://github.com/in-toto/witness)
-- [cosign-signing-gates.md](cosign-signing-gates.md)
-- [artifact-attestation-gates.md](artifact-attestation-gates.md)
-- [slsa-verification-gates.md](slsa-verification-gates.md)
-- [policy-controller-gates.md](policy-controller-gates.md)

package/docs/runbooks/zizmor-workflow-audits.md

@@ -1,81 +0,0 @@
-# Zizmor Workflow 审计手册
-
-本手册承接 `zizmor` 的工程实践，用于把 GitHub Actions workflow 的安全审计接入 PR、默认分支与治理流程。它补的是“workflow 里是否存在明显的安全审计问题、以及这些问题如何落回 review 与发布链”这一层，不替代 `actionlint`、`scorecard-supply-chain-gates`、`runner-egress-hardening`、`secret-scanning-gates` 或人工安全 review。
-
-## 适用场景
-
-- 变更涉及 `.github/workflows/`、reusable workflow、workflow call、composite action 或 job 级脚本。
-- 团队希望尽早发现 unpinned `uses:`、危险表达式、`env` 写入、secret 暴露、过宽权限和可疑 workflow 结构。
-- 仓库已经有 workflow 语法 lint，但还缺“安全视角”的审计。
-- 需要把 GitHub Actions 的潜在攻击面前置到 PR 或默认分支审查，而不是等到发布阶段才发现。
-
-## 不适用场景
-
-- 仓库没有 GitHub Actions，或者 workflow 主要是第三方托管、与当前仓库治理边界无关。
-- 团队还没有建立基本的 workflow review、token 权限收敛和 secret 管理，却期待单靠审计工具解决问题。
-- 期望 `zizmor` 替代 `actionlint` 做 YAML / 语法 / shell 检查。
-- 期望 `zizmor` 替代 `scorecard` 做仓库级供应链基线审计。
-
-## 推荐落地方式
-
-1. 先把 `zizmor` 看成 workflow 安全审计层，不要一开始就把它当成全集仓库门禁。
-2. 第一阶段优先审计高风险 workflow：
-   - 构建与发布 workflow
-   - 访问密钥、签名、attestation 或制品仓库的 workflow
-   - 使用第三方 action、reusable workflow 或复杂表达式的 workflow
-3. 审计范围先收窄到 `.github/workflows/` 与关键 workflow 片段，再逐步扩展到 reusable workflow、composite action 或远程引用。
-4. 将 `zizmor` 与现有链路分层：
-   - `actionlint` 负责 workflow 语法、结构和常见 shell 失误
-   - `scorecard-supply-chain-gates` 负责仓库级供应链基线、权限和 action pinning 的宏观审计
-   - `github-token-permissions-baseline` 负责基于真实 workflow run 收敛 `GITHUB_TOKEN` 最小权限
-   - `zizmor-workflow-audits` 负责 GitHub Actions workflow 的安全审计细节
-   - 安全评审角色 / `code-review` 负责判断这些审计结果是否真实、是否阻塞
-5. 对高风险问题，先维持人工 triage 或草稿结论，不要把所有命中都自动变成阻塞项。
-6. 结果必须回写到 `/code-review`、`/team-review` 或治理记录，不让审计结果只停在工具输出里。
-
-## 最小门禁模型
-
-- `workflow layer`：被审计的 workflow、job、step、reusable workflow
-- `audit layer`：`zizmor` 发现的风险候选，例如 unpinned uses、危险表达式、权限异常、secret 暴露
-- `triage layer`：人工确认哪些是实质风险、哪些是误报或可接受设计
-- `decision layer`：安全评审角色、`tech-lead`、`devops-engineer` 决定是否阻塞或进入治理待办
-
-重点不是“发现了多少条”，而是这些发现是否对应真实攻击面。
-
-## 重点检查项
-
-- `uses:` 是否固定到可审计的版本或 commit，而不是浮动引用
-- 表达式是否把不可信输入直接拼到 shell、路径、命令或权限边界里
-- `env`、`GITHUB_ENV`、`GITHUB_OUTPUT`、`secrets`、`vars` 是否被不当写入或外泄
-- workflow 权限是否过宽，是否存在不必要的 `write` 能力
-- 远程引用、reusable workflow、第三方 action 是否引入了意外的执行面
-- 审计结果是否能和 PR、review 结论、发布记录互相对应
-
-## 反模式
-
-- 把 `zizmor` 当成 `actionlint` 的替代品，只看安全，不看语法和结构。
-- 把 `zizmor` 当成 `scorecard` 的替代品，只看 workflow，而不看仓库级治理基线。
-- 发现高风险命中后只修一处，不回头检查同类 workflow 是否也存在同样模式。
-- 审计结果无人 triage，最后团队把命中当噪音源。
-- 只在默认分支跑审计，PR 阶段完全不看，导致问题晚到发布时才暴露。
-
-## 输出回落
-
-- PR 阶段：把高风险命中、误报判断和 triage 结论写入 review 摘要。
-- 评审阶段：在 `/team-review` 中明确哪些 workflow 风险已经确认，哪些仍需人工处理。
-- 发布阶段：若 workflow 风险仍未收敛，必须回写到 `/team-release` 的风险、放行结论或后续观察项。
-- 治理阶段：把长期存在的 workflow 风险、例外和整改计划沉淀到 runbook 或 ADR。
-
-## 许可证与使用边界
-
-- `zizmor` 采用 MIT License。
-- 启用前应确认 GitHub Actions 使用方式、审计范围、误报 triage 责任人和 workflow 维护节奏。
-- 如果团队当前还没有稳定的 workflow 语法 lint 与供应链基线审计，`zizmor` 应该先作为补充审计层，而不是唯一门禁。
-
-## 参考来源
-
-- [zizmorcore/zizmor](https://github.com/zizmorcore/zizmor)
-- [zizmor-action](https://github.com/marketplace/actions/zizmor-action)
-- [actionlint](https://github.com/marketplace/actions/actionlint)
-- [scorecard-supply-chain-gates.md](scorecard-supply-chain-gates.md)
-- [github-token-permissions-baseline.md](github-token-permissions-baseline.md)