@colin4k1024/tsp 2.4.1 → 2.4.2

package/docs/runbooks/codex-usage-scenarios.md

@@ -0,0 +1,168 @@
+---
+version: "0.1.0"
+status: draft
+created: 2026-03-28
+updated: 2026-03-28
+owner: 工程团队
+---
+
+# Codex 使用场景总览
+
+本文把 Codex 端的使用文档按“安装验证、主链执行、多 agent 编排、specialist 使用、场景演练”组织起来。
+
+## 1. 首次使用
+
+- 安装与首个闭环：[codex-quick-start.md](codex-quick-start.md)
+- 新项目接入：[project-onboarding.md](project-onboarding.md)
+- 按项目类型直接复制起手句：[../../examples/project-type-starter-playbook.md](../../examples/project-type-starter-playbook.md)
+- 按更垂直项目类型复制连续脚本：[../../examples/vertical-project-conversation-scripts.md](../../examples/vertical-project-conversation-scripts.md)
+- GitHub Actions / AI Eval / 移动端 / 合规 / 内部平台 / 数据质量 demo script：[github-actions-supply-chain-demo-script.md](github-actions-supply-chain-demo-script.md)、[ai-eval-platform-demo-script.md](ai-eval-platform-demo-script.md)、[mobile-miniapp-demo-script.md](mobile-miniapp-demo-script.md)、[security-compliance-platform-demo-script.md](security-compliance-platform-demo-script.md)、[internal-developer-platform-demo-script.md](internal-developer-platform-demo-script.md)、[data-observability-quality-demo-script.md](data-observability-quality-demo-script.md)
+- 按材料成熟度选择 vertical 场景：[../presentation/vertical-scenario-route-map.md](../presentation/vertical-scenario-route-map.md)
+- 按表格查看 vertical 材料覆盖：[vertical-scenario-capability-matrix.md](vertical-scenario-capability-matrix.md)
+- 完整主链演练：[first-team-workflow-walkthrough.md](first-team-workflow-walkthrough.md)
+
+## 2. Codex 特有工作方式
+
+- Codex 工作流要领：[codex-workflow-essentials.md](codex-workflow-essentials.md)
+- 多 Agent 编排指南：[codex-multi-agent-orchestration.md](codex-multi-agent-orchestration.md)
+- 命令与能力矩阵：[command-and-capability-matrix.md](command-and-capability-matrix.md)
+- runtime 能力总览：[runtime-capabilities-overview.md](runtime-capabilities-overview.md)
+
+## 3. 日常协作与 specialist
+
+- Specialist 命令工作簿：[specialist-commands-playbook.md](specialist-commands-playbook.md)
+- 如果你想优先体验 `/tdd`、`/harness-audit` 这类新增命令，也从 [specialist-commands-playbook.md](specialist-commands-playbook.md) 进入
+- Codex 场景化示例集：[../../examples/codex-scenario-playbook.md](../../examples/codex-scenario-playbook.md)
+- Handoff 填充指南：[handoff-filling-guide-with-examples.md](handoff-filling-guide-with-examples.md)
+- Team Intake 完整示例：[team-intake-example.md](team-intake-example.md)
+- Team Plan 完整示例：[team-plan-example.md](team-plan-example.md)
+- Team Execute 完整示例：[team-execute-example.md](team-execute-example.md)
+- Team Handoff 完整示例：[team-handoff-example.md](team-handoff-example.md)
+- Team Review 完整示例：[team-review-example.md](team-review-example.md)
+- Team Release 完整示例：[team-release-example.md](team-release-example.md)
+- API Mock 策略与生命周期手册：[api-mocking-strategy-and-lifecycle-guide.md](api-mocking-strategy-and-lifecycle-guide.md)
+- 前后端联调与验收清单：[frontend-backend-integration-acceptance-checklist.md](frontend-backend-integration-acceptance-checklist.md)
+- Consumer-Driven Contract 与 Mock 对齐指南：[consumer-driven-contract-testing-with-mock-alignment.md](consumer-driven-contract-testing-with-mock-alignment.md)
+- Team 命令快速提示：[team-commands-quick-prompts.md](team-commands-quick-prompts.md)
+- Codex 并行编排提示模板：[codex-parallel-prompt-recipes.md](codex-parallel-prompt-recipes.md)
+- 角色高频提示模板：[role-prompt-recipes.md](role-prompt-recipes.md)
+- Codex 完整对话样例：[codex-end-to-end-conversation-example.md](codex-end-to-end-conversation-example.md)
+- QA 放行对话样例：[qa-review-conversation-example.md](qa-review-conversation-example.md)
+- DevOps 发布对话样例：[devops-release-conversation-example.md](devops-release-conversation-example.md)
+- Tech Lead 收口对话样例：[tech-lead-closure-conversation-example.md](tech-lead-closure-conversation-example.md)
+- Product Manager 需求澄清对话样例：[product-manager-clarification-conversation-example.md](product-manager-clarification-conversation-example.md)
+- Project Manager 计划推进对话样例：[project-manager-planning-conversation-example.md](project-manager-planning-conversation-example.md)
+- Architect 方案设计对话样例：[architect-design-conversation-example.md](architect-design-conversation-example.md)
+- 60 秒跑通第一个 Team 命令：[first-team-command-60-seconds.md](first-team-command-60-seconds.md)
+- QA 工程师日常操作：[qa-engineer-daily-operations.md](qa-engineer-daily-operations.md)
+- DevOps 工程师日常操作：[devops-engineer-daily-operations.md](devops-engineer-daily-operations.md)
+- 项目经理日常操作：[project-manager-daily-operations.md](project-manager-daily-operations.md)
+- Tech Lead 日常操作：[tech-lead-daily-operations.md](tech-lead-daily-operations.md)
+- 产品经理日常操作：[product-manager-daily-operations.md](product-manager-daily-operations.md)
+- 架构师日常操作：[architect-daily-operations.md](architect-daily-operations.md)
+
+## 4. 共享 walkthrough
+
+- Bug 修复全流程：[bug-fix-complete-walkthrough.md](bug-fix-complete-walkthrough.md)
+- Code Review 协作演练：[code-review-collaboration-walkthrough.md](code-review-collaboration-walkthrough.md)
+- 多服务后端集成演练：[multi-service-backend-integration-walkthrough.md](multi-service-backend-integration-walkthrough.md)
+- 紧急修复发布演练：[hotfix-emergency-release-walkthrough.md](hotfix-emergency-release-walkthrough.md)
+- 前端重构演练：[frontend-refactor-walkthrough.md](frontend-refactor-walkthrough.md)
+- API 设计与演进演练：[api-design-evolution-walkthrough.md](api-design-evolution-walkthrough.md)
+- 文档更新协作演练：[documentation-update-walkthrough.md](documentation-update-walkthrough.md)
+- 构建失败处理演练：[build-failure-recovery-walkthrough.md](build-failure-recovery-walkthrough.md)
+- 需求澄清与范围管理演练：[requirement-clarity-and-scope-walkthrough.md](requirement-clarity-and-scope-walkthrough.md)
+- 系统架构设计与 ADR 演练：[system-architecture-design-walkthrough.md](system-architecture-design-walkthrough.md)
+- 金丝雀灰度发布演练：[canary-staging-release-walkthrough.md](canary-staging-release-walkthrough.md)
+- 生产事故应急响应演练：[production-incident-response-walkthrough.md](production-incident-response-walkthrough.md)
+- 发布后回滚与恢复演练：[release-rollback-recovery-walkthrough.md](release-rollback-recovery-walkthrough.md)
+- 前后端并行开发与联调演练：[frontend-backend-parallel-integration-walkthrough.md](frontend-backend-parallel-integration-walkthrough.md)
+- 并行研发协调演练：[parallel-development-coordination-walkthrough.md](parallel-development-coordination-walkthrough.md)
+- 跨角色问题分诊演练：[cross-role-issue-triage-walkthrough.md](cross-role-issue-triage-walkthrough.md)
+- GitHub Actions 与供应链治理演练：[github-actions-supply-chain-walkthrough.md](github-actions-supply-chain-walkthrough.md)
+- AI Eval 平台演练：[ai-eval-platform-walkthrough.md](ai-eval-platform-walkthrough.md)
+- 移动端与小程序交付演练：[mobile-miniapp-delivery-walkthrough.md](mobile-miniapp-delivery-walkthrough.md)
+- IaC 与 Kubernetes 平台演练：[iac-kubernetes-platform-walkthrough.md](iac-kubernetes-platform-walkthrough.md)
+- 插件与扩展平台演练：[plugin-extension-platform-walkthrough.md](plugin-extension-platform-walkthrough.md)
+- 数据与 ML Pipeline 演练：[data-ml-pipeline-walkthrough.md](data-ml-pipeline-walkthrough.md)
+- 安全与合规平台演练：[security-compliance-platform-walkthrough.md](security-compliance-platform-walkthrough.md)
+- 内部开发者平台演练：[internal-developer-platform-walkthrough.md](internal-developer-platform-walkthrough.md)
+- 数据可观测性与质量平台演练：[data-observability-quality-walkthrough.md](data-observability-quality-walkthrough.md)
+
+## 5. 一页速查
+
+- 前端缺陷修复一页速查：[frontend-bugfix-one-page.md](frontend-bugfix-one-page.md)
+- 发布收口一页速查：[release-closure-one-page.md](release-closure-one-page.md)
+- 事故分诊一页速查：[incident-triage-one-page.md](incident-triage-one-page.md)
+- 管理层价值速查一页：[executive-value-one-page.md](executive-value-one-page.md)
+
+## 6. 受众阅读路径
+
+- 实施接入阅读路径：[implementation-onboarding-reading-path.md](implementation-onboarding-reading-path.md)
+- 团队培训阅读路径：[team-training-reading-path.md](team-training-reading-path.md)
+
+## 7. 排障与规范
+
+- 安装与使用排障：[troubleshooting.md](troubleshooting.md)
+- 完整使用手册：[team-skills-usage.md](team-skills-usage.md)
+- 命令输出合同：[team-command-output-contracts.md](team-command-output-contracts.md)
+- 发布治理阅读路径：[release-governance-reading-path.md](release-governance-reading-path.md)
+- 示例总索引：[../../examples/INDEX.md](../../examples/INDEX.md)
+
+## 8. 企业扩展与发布收口
+
+- 自定义 overlay 扩展：[custom-overlay.md](custom-overlay.md)
+- 自定义 overlay 创建入口：[custom-overlay.md](custom-overlay.md)
+- Langfuse 追踪与可观测性集成指南：[langfuse-and-observability-integration-guide.md](langfuse-and-observability-integration-guide.md)
+- 发布治理阅读路径：[release-governance-reading-path.md](release-governance-reading-path.md)
+
+## 9. 推荐阅读路径
+
+### 8.1 第一次用 Codex
+
+1. [codex-quick-start.md](codex-quick-start.md)
+2. [codex-workflow-essentials.md](codex-workflow-essentials.md)
+3. [first-team-workflow-walkthrough.md](first-team-workflow-walkthrough.md)
+4. [../../examples/codex-scenario-playbook.md](../../examples/codex-scenario-playbook.md)
+
+### 8.2 需要并行加速
+
+1. [codex-multi-agent-orchestration.md](codex-multi-agent-orchestration.md)
+2. [specialist-commands-playbook.md](specialist-commands-playbook.md)
+3. [handoff-filling-guide-with-examples.md](handoff-filling-guide-with-examples.md)
+
+### 8.3 需要新增能力路径
+
+1. 想先看命令、skills、runtime 全景：看 [command-and-capability-matrix.md](command-and-capability-matrix.md)
+2. 想体验 `/tdd`、`/harness-audit`：看 [codex-quick-start.md](codex-quick-start.md) 和 [../../examples/codex-scenario-playbook.md](../../examples/codex-scenario-playbook.md)
+3. 想理解并行、budget、compact、cost、instinct：看 [runtime-capabilities-overview.md](runtime-capabilities-overview.md)
+
+### 8.4 需要联调和跨角色协作
+
+1. [frontend-backend-parallel-integration-walkthrough.md](frontend-backend-parallel-integration-walkthrough.md)
+2. [parallel-development-coordination-walkthrough.md](parallel-development-coordination-walkthrough.md)
+3. [cross-role-issue-triage-walkthrough.md](cross-role-issue-triage-walkthrough.md)
+
+### 8.5 需要质量或发布收口
+
+1. [qa-engineer-daily-operations.md](qa-engineer-daily-operations.md)
+2. [devops-engineer-daily-operations.md](devops-engineer-daily-operations.md)
+3. [hotfix-emergency-release-walkthrough.md](hotfix-emergency-release-walkthrough.md)
+
+### 8.6 需要需求、架构或发布治理
+
+1. [product-manager-daily-operations.md](product-manager-daily-operations.md)
+2. [architect-daily-operations.md](architect-daily-operations.md)
+3. [canary-staging-release-walkthrough.md](canary-staging-release-walkthrough.md)
+4. [production-incident-response-walkthrough.md](production-incident-response-walkthrough.md)
+
+### 8.7 需要自定义 overlay 扩展能力
+
+1. 想创建自定义 overlay，看 [custom-overlay.md](custom-overlay.md)
+2. 
+
+### 8.8 按受众快速进入
+
+1. 管理层先看 [executive-value-one-page.md](executive-value-one-page.md)
+2. 实施接入先看 [implementation-onboarding-reading-path.md](implementation-onboarding-reading-path.md)
+3. 团队培训先看 [team-training-reading-path.md](team-training-reading-path.md)

package/docs/runbooks/codex-workflow-essentials.md

@@ -0,0 +1,88 @@
+---
+version: "0.1.0"
+status: draft
+created: 2026-03-28
+updated: 2026-03-28
+owner: 工程团队
+---
+
+# Codex 工作流要领
+
+本文说明 Codex 端的工作方式和 Claude 有什么差别，以及为什么 Codex 更适合“主链 + specialist + 并行 agent”的组合。
+
+如果你想先看完整命令面，读 [command-and-capability-matrix.md](command-and-capability-matrix.md)。如果你想理解并行之外的预算、compact、observation、instinct 等后台机制，读 [runtime-capabilities-overview.md](runtime-capabilities-overview.md)。
+
+## 1. Codex 的适用特点
+
+- 更适合围绕插件目录连续工作
+- 更适合把多个 agent 结果并行收集再回到主链
+- 更适合较大、依赖较多的任务
+
+## 2. 安装后的第一步
+
+完成 [codex-quick-start.md](codex-quick-start.md) 后，建议再做三件事：
+
+1. 确认插件目录里能看到命令和 agents
+2. 选一个真实任务跑最小闭环
+3. 明确哪些 specialist 会成为你的高频工具
+4. 区分哪些是显式命令，哪些是 runtime 自动生效的后台能力
+
+## 3. 主链在 Codex 中怎么跑
+
+推荐顺序：
+
+1. `/team-intake`
+2. `/team-plan`
+3. 按任务形态插入 `/plan`、`/tdd`、`/multi-*`、`/build-fix`、`/verify`
+4. `/handoff`
+5. `/team-review` 或 `/team-release`
+
+## 4. Specialist 如何插入
+
+高频用法：
+
+- 方案复杂：`/plan`
+- 测试先行：`/tdd`
+- 前端复杂：`/multi-frontend`
+- 后端复杂：`/multi-backend`
+- 构建问题：`/build-fix`
+- 结果验证：`/verify`
+- 平台自检：`/harness-audit`
+
+建议你把 specialist 分成三类理解：
+
+- 面向业务交付的命令：`/plan`、`/tdd`、`/build-fix`、`/verify`
+- 面向并行编排的命令：`/multi-frontend`、`/multi-backend`
+- 面向平台治理的命令：`/harness-audit`
+
+## 5. 结果聚合原则
+
+Codex 的关键不是“多跑几个 agent”，而是“能不能把结果安全回收到主链”。
+
+建议每次 specialist 之后都补：
+
+```text
+请把上面的专项结论整理为可直接进入 /handoff 的格式。
+```
+
+如果刚跑完的是 `/tdd`，再补一句：
+
+```text
+请把测试约束、实现顺序和验证口径整理成可直接进入 /team-execute 的动作清单。
+```
+
+如果刚跑完的是 `/harness-audit`，再补一句：
+
+```text
+请把高优先级缺口拆成文档、命令、skills、hooks 四类收敛动作。
+```
+
+## 6. 常见错误
+
+- 并行跑了很多 agent，却没有统一收口
+- specialist 跳过主链直接变成最终结论
+- 复杂任务没有先做 intake 和 plan
+- 把 `/harness-audit` 当成业务任务评审命令使用
+- 不区分显式命令和 runtime，导致把 observation、compact 误写成“手动执行步骤”
+
+如果你需要更深入的并行编排，继续看 [codex-multi-agent-orchestration.md](codex-multi-agent-orchestration.md)；如果你想直接复制高频表达方式，继续看 [codex-parallel-prompt-recipes.md](codex-parallel-prompt-recipes.md)；如果你想看平台能力自检怎么做，继续看 [specialist-commands-playbook.md](specialist-commands-playbook.md)。

package/docs/runbooks/command-and-capability-matrix.md

@@ -0,0 +1,162 @@
+---
+version: "2.3.0"
+status: draft
+created: 2026-03-29
+updated: 2026-04-18
+owner: 工程团队
+doc_tier: entry
+last_verified: 2026-04-18
+source_of_truth:
+  - ../../README.md
+  - ../../AGENTS.md
+  - ../../commands/
+---
+
+# 命令与能力矩阵
+
+本文只回答一个问题：当前平台到底有哪些公开命令、ECC 增强能力和 runtime 能力，以及它们通常怎么组合。BMAD 在这里继续作为方法来源，不再暴露成第二套 `/bmad-*` 工作流。
+
+## 0. 文档生命周期字段
+
+| 字段 | 当前值 | 说明 |
+|------|--------|------|
+| `status` | `draft` | 文档成熟度；未标记 `active` 前默认按草案迭代 |
+| `doc_tier` | `entry` | 入口层文档；与 README / AGENTS 一起维护公开口径 |
+| `last_verified` | `2026-04-17` | 最近一次人工验证日期（命令面与入口一致性） |
+| `source_of_truth` | `README.md`、`AGENTS.md`、`commands/` | 命令定义与公开口径的权威来源 |
+
+## 1. 公开命令总表
+
+| 类型 | 命令 | 作用 | 典型输出回落位置 |
+|------|------|------|------------------|
+| 主链入口 | `/team-help` | 根据当前阶段、artifacts、handoff 与阻塞项推荐下一条主链命令 | `/team-intake`、`/team-plan`、`/team-execute`、`/team-closeout` |
+| 主链 | `/team-intake` | 锁目标、范围、约束、角色和候选扩展 | `/team-plan` |
+| 主链 | `/team-plan` | 完成 challenge / design 收口、形成 implementation-readiness | `/team-execute`、`/handoff` |
+| 主链 | `/handoff` | 结构化交接与 readiness proof 收口 | `/team-review`、`/team-release` |
+| 主链 | `/team-execute` | 消费 readiness proof 执行实现、自测与执行记录 | `/handoff` |
+| 主链 | `/team-review` | 质量结论、阻塞、放行建议 | `/team-release` |
+| 主链 | `/team-release` | 发布方案、观察窗口、回滚与责任链 | `/team-closeout` |
+| 主链 | `/team-closeout` | 最终验收、观察窗口收口、backlog 回写 | 任务关闭 / follow-up |
+| specialist | `/plan` | 深度规划、阶段拆解 | `/team-plan`、`/handoff` |
+| specialist | `/tdd` | 测试先行、red-green-refactor 路径 | `/team-execute`、`/handoff` |
+| specialist | `/code-review` | 实现风险、回归与质量审查 | `/handoff`、`/team-review` |
+| specialist | `/build-fix` | 构建与校验失败定位、修复 | `/team-execute`、`/handoff` |
+| specialist | `/verify` | 关键路径验证、放行前证据 | `/team-review`、`/team-release` |
+| specialist | `/multi-frontend` | 前端并行分析：实现 / UIUX / QA | `/handoff`、`/team-plan` |
+| specialist | `/multi-backend` | 后端并行分析：接口 / 权限 / 测试 | `/handoff`、`/team-plan` |
+| 快捷执行 | `/quick` | 小范围低风险任务的快速闭环 | `/handoff`、`/team-review` |
+| 快捷执行 | `/pause` | 暂停当前会话并生成恢复快照 | `/resume` |
+| 快捷执行 | `/resume` | 从最近暂停状态恢复会话继续执行 | `/team-*` 主链或 `/quick` |
+| 进阶能力 | `/pua` | 高能动性与高压闭环推进 | `/team-execute`、`/team-release` |
+| 进阶能力 | `/model-route` | 按任务复杂度和预算建议模型档位 | 当前任务上下文 |
+| 进阶能力 | `/evolve` | 管理 instinct/gene 演进生命周期 | `docs/memory/`、演进资产 |
+| 进阶能力 | `/learn` | 从会话提炼复用模式并沉淀 | 本地 skills 资产 |
+| 进阶能力 | `/agent-dev` | 交互式 Agent 开发 Workshop | `skills/`、`agents/`、`commands/` |
+| 平台体检 | `/harness-audit` | 审视平台覆盖度、hook 有效性、文档质量和集成深度 | 平台治理、文档补齐、下一轮收敛 |
+
+## 2. 主链最小闭环
+
+1. 先用 `/team-help` 判断入口，不直接猜下一条命令
+2. 正式主链输出统一通过 `npm run artifact:persist -- ...` 落到 `docs/artifacts/`
+3. `/team-plan` 负责收口 challenge、design review 和 implementation-readiness
+4. `/team-execute` 只消费已具备 readiness proof 的 story-sized execution unit
+5. 发布后仍需 `/team-closeout` 收完观察窗口
+6. `/team-help` 到 `/team-release` 默认带上 `karpathy-guidelines` 这层行为护栏；它用于暴露假设、收敛 scope、保持改动外科化，但不是新的阻塞门槛
+
+## 3. ECC 能力分组
+
+### 3.1 调试与验证
+
+| 能力 | 作用 | 常搭命令 |
+|------|------|----------|
+| `doc-architecture` | 文档发现、建模、一致性审计并映射到 artifacts | `/team-intake`、`/team-plan`、`/team-review` |
+| `graphify` | 可选知识图谱能力，用于 brownfield 结构扫描、依赖路径分析与架构问答证据 | `/team-help`、`/team-plan`、`/team-execute` |
+| `gitnexus` | 受控可选代码智能能力，用于 MCP 查询、impact、detect_changes、多仓图谱证据 | `/team-help`、`/team-plan`、`/team-execute`、`/team-review` |
+| `karpathy-guidelines` | 主流程默认行为护栏：先暴露假设、优先简单方案、限定改动边界、先锁成功标准 | `/team-help`、`/team-intake`、`/team-plan`、`/team-execute`、`/team-review`、`/team-release` |
+| `browser-smoke-testing` | 浏览器主路径与 smoke 证据 | `/team-execute`、`/verify`、`/team-release` |
+| `pairwise-test-design` | 组合爆炸压缩 | `/team-plan`、`/team-review` |
+| `testcontainers-integration-testing` | 容器化集成验证 | `/team-execute`、`/verify` |
+| `systematic-debugging` | 根因定位而不是表面修错 | `/build-fix`、`/team-execute` |
+| `java-unit-test` | Java 单测与验证 | `/tdd`、`/team-execute` |
+| `maven-qa` | Java/Maven 质量门禁 | `/team-review`、`/verify` |
+| `eval-harness` | eval-driven development、pass@k 与回归基线 | `/tdd`、`/verify` |
+
+### 3.2 编排与效率
+
+| 能力 | 作用 | 常搭命令 |
+|------|------|----------|
+| `parallel-execution` | worktree / 并行实例 / 级联任务 | `/multi-frontend`、`/multi-backend` |
+| `strategic-compact` | 长会话压缩与上下文重组 | 长会话中的 specialist 与主链 |
+| `cost-aware-llm-pipeline` | 模型选择、成本控制、上下文预算 | 长会话、复杂任务规划 |
+| `harness-audit` | 平台能力评分与改进优先级 | `/harness-audit` |
+
+### 3.3 学习与记忆
+
+| 能力 | 作用 | 常搭命令 |
+|------|------|----------|
+| `error-experience-library` | 错误模式沉淀、历史方案检索 | `/build-fix`、`/team-execute` |
+| `continuous-learning` | 项目级 / 全局级模式演进 | 长期使用、平台演进 |
+
+## 4. runtime 能力总览
+
+| 类别 | 当前入口 | 作用 |
+|------|----------|------|
+| session memory | `scripts/hooks/session-start-bootstrap.js`、`scripts/hooks/session-start.js`、`scripts/hooks/session-end.js` | 会话摘要、待办与上下文连续性 |
+| governance capture | `scripts/hooks/governance-capture.js` | secret / approval / policy 信号采集 |
+| cost awareness | `scripts/hooks/cost-tracker.js` | token 与成本记录 |
+| compact readiness | `scripts/hooks/suggest-compact.js`、`scripts/hooks/pre-compact.js` | 长会话整理与 compact 提示 |
+| MCP health | `scripts/hooks/mcp-health-check.js` | MCP 健康检测与失败信号 |
+| edit quality | `scripts/hooks/quality-gate.js` + Stop hooks | 编辑后最小质量闸口 |
+
+完整说明见 [runtime-capabilities-overview.md](runtime-capabilities-overview.md)。
+
+## 5. 安装与落盘关联
+
+- Claude legacy install 现在会复制 `scripts/hooks/*.js`，并在 `settings.json` 中清理旧 `.py` hook 引用
+- Codex / Claude 安装都以当前平铺的 `skills/` 为正式能力目录，不再把旧三层目录当成现行结构
+- 用户面任务产出统一通过 `artifact:persist` 落盘，不依赖“只在对话里说过”
+
+## 6. 推荐组合
+
+### 6.1 新功能
+
+1. `/team-help`
+2. `/team-intake`
+3. `/team-plan`
+4. 需要测试先行时补 `/tdd`
+5. `/team-execute`
+6. `/handoff`
+7. `/team-review`
+8. `/team-release`
+9. `/team-closeout`
+
+### 6.2 小修复
+
+1. `/team-help`
+2. `/quick` 或 `/team-intake`
+3. `/code-review` 或 `/build-fix`
+4. `/handoff`
+5. `/team-review`
+
+### 6.3 平台治理
+
+1. `/team-help`
+2. `/team-plan`
+3. `/harness-audit`
+4. 对照 README、quick start、usage runbooks 和 install/runtime 测试补齐入口
+
+### 6.4 Brownfield 结构扫描（可选）
+
+1. `/team-help`
+2. `/update-codemaps` 生成轻量现状快照
+3. 轻量结构证据执行 `npm run graphify:doctor`；深影响面或 MCP 证据执行 `npm run gitnexus:doctor`
+4. Graphify 执行 `build/query/path/explain`，或 GitNexus 执行受控索引后查询 `impact/detect_changes/context`
+5. `/team-plan` 消费图谱证据收口 challenge/design/readiness
+6. `/team-execute` 与 `/team-review` 持续引用图谱证据，不创建并行责任链
+
+## 7. 下一步看什么
+
+- 想看 quick start：看 [claude-quick-start.md](claude-quick-start.md) 和 [codex-quick-start.md](codex-quick-start.md)
+- 想看接入流程：看 [project-onboarding.md](project-onboarding.md)
+- 想看完整使用手册：看 [team-skills-usage.md](team-skills-usage.md)
+- 想看后台机制：看 [runtime-capabilities-overview.md](runtime-capabilities-overview.md)

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

@@ -0,0 +1,84 @@
+# Conftest Policy 门禁手册
+
+本手册承接 `open-policy-agent/conftest` 的工程实践，用于把 policy-as-code 预检接入 PR、评审和发布准备。它补的是“在合并或发布前，先用 Rego 策略检查 structured config 是否满足团队规则”这一层，不替代 `trivy-security-gates`、`policy-controller-gates`、`dependency-review-gates` 或人工评审。
+
+## 适用场景
+
+- 变更涉及 Kubernetes YAML、Helm values、Terraform、JSON、YAML、Docker Compose 或其他结构化配置。
+- 团队希望把“配置是否符合团队规则”从人工 review 中抽出来，变成可重复执行的 policy check。
+- 需要在 PR 或发布前提前拦住高风险配置，例如不安全的资源限制、镜像来源、权限、暴露端口或命名规范问题。
+- 团队希望把配置规则集中成 Rego policy，而不是把同类检查散落在多个脚本、lint 工具或 review checklist 里。
+
+## 不适用场景
+
+- 只想扫描漏洞、secret 或镜像内容，却没有明确的配置策略要表达。
+- 团队还没有准备好维护 Rego policy、测试样例和例外流程。
+- 期望 Conftest 替代 `trivy-security-gates` 对镜像、文件系统和 IaC 漏洞 / misconfiguration 的检查。
+- 期望 Conftest 替代 `policy-controller-gates` 在 Kubernetes admission 层的强制执行。
+- 变更只是代码逻辑，而不是结构化配置或策略输入。
+
+## 推荐落地方式
+
+1. 先从单一配置域开始，不要一上来就把所有文件类型和所有规则都放进同一套 policy。
+2. 第一阶段优先覆盖高价值、低歧义的规则：
+   - Kubernetes 资源的安全默认值
+   - Helm / values 的环境约束
+   - Terraform 的命名、标签、权限或暴露面规则
+   - JSON / YAML 配置里的结构性约束
+3. 将 Conftest 与现有链路分层：
+   - `kubeconform-schema-gates` 负责 Kubernetes manifest 的 schema 级结构校验
+   - `checkov-iac-gates` 负责 IaC 安全与合规基线、内置规则和图关系检查
+   - `trivy-security-gates` 负责漏洞、secret 和 IaC 扫描结果
+   - `conftest-policy-gates` 负责配置结构、团队规则和 policy-as-code 预检
+   - `kyverno-policy-gates` 负责 Kubernetes 集群内的 admission、background scan 和 policy report 执行
+   - `policy-controller-gates` 负责在集群 admission 层把确认过的策略强制执行
+4. 先在 PR 级或 pre-merge 阶段跑 policy check，再决定是否把某些规则升级成发布门禁。
+5. 结果必须回写到 `/team-review`、`/team-release` 或对应配置仓库，不要只停在命令输出里。
+
+## 最小门禁模型
+
+- `target layer`：Kubernetes、Terraform、Helm、YAML、JSON 或其他结构化配置
+- `policy layer`：Rego policy、规则集和例外条件
+- `evaluation layer`：Conftest 对输入配置执行 policy 计算
+- `decision layer`：`qa-engineer`、`devops-engineer`、`tech-lead` 决定是否阻塞合并或发布
+
+重点不是“跑过一个 policy checker”，而是团队是否能稳定回答“这条配置违反了哪条规则、为什么、是否允许例外”。
+
+## 重点检查项
+
+- 是否覆盖了团队真正关心的配置类型，而不是只做样例级别的演示
+- Rego 规则是否足够明确，避免把模糊判断写成难以维护的 policy
+- policy 是否和 Kubernetes / Terraform / Helm 的实际使用方式对齐
+- 是否把规则和例外分开管理，避免 policy 越堆越多后无人维护
+- 是否存在大量误报或重复规则，导致团队把 Conftest 当成噪音源
+- 对于高风险配置，失败结果是否能回写到 review 或 release 结论，而不是只留在本地输出
+
+## 反模式
+
+- 只把 Conftest 当成“还能跑的另一个 lint 工具”，没有明确 policy owner。
+- 规则写得过于宽泛，最后任何配置都能解释成通过。
+- policy 只在 CI 里执行，团队却没有样例、基线和 triage 责任。
+- 把它当成漏洞扫描器，忽略它本质上是配置策略测试工具。
+- 既有 `trivy-security-gates` 又有 `policy-controller-gates`，却没有说明 Conftest 在 PR 级和发布前的定位。
+
+## 输出回落
+
+- PR 阶段：把 policy 命中、例外判断和修改建议写入 review 摘要。
+- 评审阶段：在 `/team-review` 中说明哪些配置问题来自 Conftest，哪些已经人工确认或需要阻塞。
+- 发布阶段：若配置违反关键策略，必须回写到 `/team-release` 的风险、放行结论或后续观察项。
+- 治理阶段：把长期稳定的 policy、基线和例外沉淀到配置仓库或治理文档中。
+
+## 许可证与使用边界
+
+- `open-policy-agent/conftest` 采用 Apache-2.0。
+- 引入前应确认团队是否具备维护 Rego policy、样例输入和例外流程的能力。
+- 若团队已经需要在集群内强制执行策略，应把 `conftest-policy-gates` 视为 PR / 发布前预检，而不是 admission 层的最终门禁。
+
+## 参考来源
+
+- [open-policy-agent/conftest](https://github.com/open-policy-agent/conftest)
+- [kubeconform-schema-gates.md](kubeconform-schema-gates.md)
+- [checkov-iac-gates.md](checkov-iac-gates.md)
+- [trivy-security-gates.md](trivy-security-gates.md)
+- [kyverno-policy-gates.md](kyverno-policy-gates.md)
+- [policy-controller-gates.md](policy-controller-gates.md)

package/docs/runbooks/consumer-driven-contract-testing-with-mock-alignment.md

@@ -0,0 +1,45 @@
+---
+version: "0.1.0"
+status: draft
+created: 2026-03-28
+updated: 2026-03-28
+owner: 工程团队
+---
+
+# Consumer-Driven Contract 与 Mock 对齐指南
+
+本文聚焦 consumer-driven contract testing 和 Mock 的协同关系，解决“Mock 能跑、Pact 也能过，但真实接口仍然错位”的问题。
+
+## 1. 核心原则
+
+- Mock 负责提早开发与局部验证
+- Contract 负责 consumer/provider 的行为约定
+- 真实联调负责确认运行时细节没有偏离
+
+## 2. 对齐节奏
+
+- consumer 先声明真正依赖的行为
+- Mock 只表达当前 consumer 需要的最小集合
+- provider verification 结果要回写 contract 和 handoff
+- 真实接口联调后，清理不再成立的 Mock 假设
+
+## 3. 需要同步的内容
+
+- 字段是否必填
+- 错误码和错误语义
+- 分页、排序、权限、幂等行为
+- 版本策略和兼容边界
+
+## 4. 常见错误
+
+- 用 Mock 固化 provider 的实现细节
+- Contract 变了，但 consumer Mock 没变
+- provider verification 失败后没有明确归因
+
+## 5. 建议落点
+
+- 契约更新回写到 [../../templates/api-contract.md](../../templates/api-contract.md)
+- 联调结果回写到 handoff 与 `/team-review`
+- 发布前把高风险契约差异写入 `/team-release`
+
+与这些文档配合阅读：[contract-testing-playbook.md](contract-testing-playbook.md)、[api-design-evolution-walkthrough.md](api-design-evolution-walkthrough.md)

package/docs/runbooks/contract-testing-playbook.md

@@ -0,0 +1,78 @@
+# Contract Testing 手册
+
+本手册承接 `pact-foundation/pact-jvm` 的工程实践，用于把 consumer/provider contract testing 接入 API 设计、实现验证和发布准备。它补的是“调用方与提供方对同一接口的真实约定是否一致”这一层，不替代 `api-contract`、`api-breaking-change-gates`、`api-lint-gates` 或人工架构评审。
+
+配套实践可继续看 [api-mocking-strategy-and-lifecycle-guide.md](api-mocking-strategy-and-lifecycle-guide.md)、[frontend-backend-integration-acceptance-checklist.md](frontend-backend-integration-acceptance-checklist.md) 与 [consumer-driven-contract-testing-with-mock-alignment.md](consumer-driven-contract-testing-with-mock-alignment.md)。
+
+## 适用场景
+
+- 多服务协作时，consumer 和 provider 不同团队开发，接口语义容易口头对齐、代码上失配。
+- 想在联调前就提前暴露请求字段、响应字段、状态码、鉴权或行为约定的偏差。
+- 需要把“这个接口对调用方到底意味着什么”沉淀成可执行、可回放、可验证的契约。
+- 接口实现变化频繁，但调用方又依赖稳定行为，适合用契约测试兜住协作边界。
+
+## 不适用场景
+
+- 当前接口契约还没稳定，连基本请求响应形状都在频繁漂移。
+- 只有单体内局部方法调用，没有明确的 consumer/provider 边界。
+- 团队没有人愿意维护 pact 文件、provider verification 或失败 triage。
+- 期望 contract testing 替代 API 设计、breaking change 检查或系统级集成测试。
+
+## 推荐落地方式
+
+1. 先明确要覆盖的边界，不要一上来把所有接口都做成契约测试。
+2. 第一阶段先挑最有价值的调用链：
+   - 高价值 consumer
+   - 经常联调失败的 provider
+   - 容易回归的鉴权、分页、错误处理和字段映射
+3. 先让 consumer 产出稳定 pact，再让 provider 做 verification，不要反过来用 provider 的实现细节去“猜” consumer 约定。
+4. 将 contract testing 与现有 API 链路分层：
+   - `api-contract` 负责接口语义与文档约定
+   - `api-lint-gates` 负责 spec 结构和风格约束
+   - `api-breaking-change-gates` 负责向后兼容性检查
+   - `contract-testing-playbook` 负责 consumer/provider 的运行时契约验证
+5. 如果团队有发布节奏，先把契约验证放进 PR 或 pre-merge 阶段，再决定是否把 provider verification 也纳入 release gate。
+6. 结果必须回写到 `/team-review`、`/team-release` 或 `api-contract`，不要只停在某个模块测试日志里。
+
+## 最小门禁模型
+
+- `contract layer`：consumer 产出的 pact 文件或契约描述
+- `mock layer`：consumer 测试时使用的 mock service 或 stub
+- `verification layer`：provider 对 pact 的验证结果
+- `decision layer`：`architect`、`backend-engineer`、`qa-engineer`、`tech-lead` 判断是否阻塞
+
+工具负责把交互录下来，团队负责判断这些交互是不是产品真正需要的约定。
+
+## 重点检查项
+
+- consumer 是否只表达真正依赖的行为，而不是把内部实现细节也固化进 pact
+- provider verification 是否覆盖了关键路径、错误响应和边界条件
+- pact 文件是否稳定、可回放、可版本化，而不是每次跑出来都不一样
+- 当接口变化时，是否能清楚区分“consumer 需要改”还是“provider 需要兼容”
+- 失败结果是否能定位到具体交互，而不是只看到“verification failed”
+
+## 反模式
+
+- 把 provider 的实现细节硬塞进 consumer pact，导致契约变成伪测试。
+- 只给 happy path 写 pact，错误响应和边界态完全没覆盖。
+- pact 文件一变就全量重写，没有版本意识，也没有变更解释。
+- 只有 consumer 端跑了 mock，provider 端从未做 verification。
+- 契约测试失败后没人 triage，最后团队默认忽略这条门禁。
+
+## 输出回落
+
+- 设计阶段：把需要稳定的请求响应、错误码和行为约定回写到 [api-contract.md](../../templates/api-contract.md) 或接口说明中。
+- 评审阶段：在 `/team-review` 中说明哪些 pact 变更是预期内的，哪些需要 provider 兼容或 consumer 回滚。
+- 发布阶段：若契约验证仍存在未关闭的高风险问题，必须同步到 `/team-release` 的放行结论或观察项。
+
+## 许可证与使用边界
+
+- `pact-foundation/pact-jvm` 采用 Apache-2.0。
+- 引入前应确认 JVM 版本、构建工具、provider verification 运行环境，以及团队是否有维护 pact 资产的责任人。
+
+## 参考来源
+
+- [pact-foundation/pact-jvm](https://github.com/pact-foundation/pact-jvm)
+- [api-contract.md](../../templates/api-contract.md)
+- [api-breaking-change-gates.md](api-breaking-change-gates.md)
+- [api-lint-gates.md](api-lint-gates.md)