PatchPilot — 风险自适应的目标驱动 AI Coding 工作流

> PatchPilot 是面向真实代码仓库的目标驱动 AI Coding 工作流，通过风险自适应的代码理解、范围控制、实现、验证与审查，让 Agent 更可靠地修改代码。

1. 产品定位

不是让 AI 写更多代码，而是让 AI 更可靠地改对代码。

本 Skill 面向真实代码仓库：通过 codebase-memory-mcp（CBM） 的代码知识图谱理解调用链和变更影响，再用阿里开源的 Open Code Review（OCR） 审查实际变更，并以 Source / Git / Build / Test / Runtime 作为最终事实依据。

最终原则：Analyze enough. Change minimally. Verify always. Remember decisions. Scale workflow by risk.
（充分分析、最小修改、始终验证、记住决策——工作流强度按风险伸缩。）

2. 触发 / 不触发边界

核心调用判断：当任务最终需要理解、修改、验证、分析影响或 Review 一个真实代码仓库时，使用本 Skill。

典型请求：接手陌生仓库 ｜ 理解模块 ｜ 新增功能 ｜ 修改业务逻辑 ｜ 修复 Bug / 测试 ｜ 重构 ｜ 修改 API / 状态 / 数据 / 配置 / 依赖 ｜ 性能 / 兼容性 / 安全修复 ｜ 分析修改影响 ｜ Review Diff / PR ｜ 继续 Roadmap 中的真实开发 Goal。

不触发：纯产品构思 / PRD 讨论 ｜ 市场与商业分析 ｜ 项目排期 ｜ 团队任务管理 ｜ 纯文案 ｜ 与代码仓库无关的一般任务。这些工作进入真实代码实现阶段后，再使用本 Skill。

新项目边界：支持从零开始的项目，但完整核心能力从真实代码仓库和最小代码骨架建立后开始发挥。只有想法、没有仓库时，本 Skill 只负责：确定第一个可执行开发 Goal ｜ 明确 Scope / Non-goals ｜ 定义 Acceptance Criteria ｜ 建立最小代码骨架。此时不得伪装 CBM / OCR 已能完整发挥——无代码 → CBM 缺少分析对象；无 Diff → OCR 缺少审查对象。最小代码骨架存在后，进入正常 ITERATION。

Goal 粒度：Goal = 一个可独立实现、验证和验收的软件开发目标。正确粒度示例：新增 OAuth 登录 ｜ 修复缓存失效 Bug ｜ 为 API 增加分页 ｜ 迁移数据结构 ｜ 重构模块但保持公开行为。错误粒度：把整个产品做完 ｜ 全面优化系统 ｜ 提升整个研发效率——大型项目拆成多个可验证 Goal。

3. 四种入口模式（Mode × Risk 二元选路）

工作流只由两个轴决定：入口模式（做什么）× 风险等级（做多深）。组合记法 模式 + L级别（如 ITERATION + L2）。

协作风格（Collaboration Style，可选）

在 Mode × Risk 之外可附加一个风格标注（记法如 ITERATION + L2 + Personal），它不是工作流第三轴，只影响表达方式：沟通详细程度、报告长度、是否主动建议沉淀工程记忆、是否输出更详细审计信息。三档：Personal（默认，个人项目 / 低摩擦）、Team（共享仓库 / 关键决策显式确认 / 变更可追溯）、High Assurance（安全敏感 / 生产关键 / 合规语境，检查点全部显式执行）。风格选择可由 Agent 依据 Goal 信号推荐、用户可覆盖，未选择时自动采用推荐档并记录理由。

风格不得：降低 Risk Level ｜ 跳过 Required Validation ｜ 跳过 OCR Gate ｜ 跳过 Runtime Verification ｜ 放宽 Authorization Boundary。风格与风险冲突时按更高风险档执行——支付 / 认证 / 安全 / 迁移类变更无论何种风格都照常升 L4。信号表与交互模板见 references/execution.md。

4. Goal Contract（含变更边界与授权）

将当前任务整理为 Goal Contract；缺少非关键内容时采用最小安全假设并显式记录，缺失信息会实质改变范围、风险、兼容性或方案时，先向用户说明并取得方向。Goal Contract 同时承担 Change Boundary Contract 职责。

Goal:               本轮唯一目标
Scope:              允许修改的模块 / 文件
Allowed Changes:    为达成 Goal 所必需的具体改动类型（必要时列白名单）
Forbidden Changes:  明确禁止的改动（未显式允许时默认禁止）
Non-goals:          明确不做什么
Acceptance Criteria: 完成的可检查条件
Validation Plan:    需要执行哪些测试、构建、运行、静态检查或人工验证

Risk Level:             L0–L4（完整 Risk Assessment 见 §6）
Required Evidence Level: 目标最低证据等级 E0–E4（见 §8）

Authorization:
  code_changes:       allowed | denied
  commit:             allowed | denied
  push:               allowed | denied
  dependency_install: allowed | denied
  config_write:       allowed | denied
  cbm_index_write:    allowed | denied
  memory_write:       none | existing_only | create_allowed

授权不能互相推断：

代码修改授权 != Commit 授权
Commit 授权 != Push 授权
Review 通过 != 发布授权
CBM 使用授权 != CBM 索引写入授权
代码 Scope != Engineering Memory 写入 Scope

memory_write 默认 none：existing_only = 只可更新既有 .project-memory/；create_allowed = 允许首次创建；不能因为目录已存在就默认允许写入。Engineering Memory 的定位（CBM = What/Where，Memory = Why）、文件模板与治理规则见 references/engineering-memory.md。

Tool Availability 类字段只能记录当前会话实际状态：MCP 已注册但工具未暴露时不得写 AVAILABLE，无证据时写 UNKNOWN；工具不可用不得降低验收标准。

Change Containment（必需性自检）

修改任何代码前自检："Is this change required to achieve the stated goal?"（这个改动是达成既定目标所必需的吗？）

• 必需 → 在 Allowed Changes 范围内执行。
• 非必需 → 不修改，记录为 out-of-scope observation（位置 / 现象 / 建议一句话，转入 Roadmap / Issue / 报告 Next；不展开分析、不提前实现）。
• 不确定 → 默认按非必需处理；确有必要时向用户说明并取得方向。

默认 Forbidden Changes（未显式允许时一律禁止）：未被要求的重构 ｜ 依赖升级（含 lockfile）｜ 命名清理 ｜ 架构变更 ｜ 无关格式化。补充判定：格式化工具作用于本次已修改的文件属允许范围；作用于未修改文件属无关格式化，禁止。Forbidden 清单与 Non-goals 冲突时以更严格者为准；用户显式覆盖时必须在 Contract 中记录该授权。

Scope Expansion Request（禁止静默扩张）

实现阶段发现 Scope 之外的必需改动时，必须先更新 Change Boundary Contract（把新边界显式写入 Allowed / Forbidden Changes），禁止静默扩张：

• 用户原始授权已明确覆盖该类扩张 → 说明变更、影响和风险后继续。
• 出现以下任一情况 → 必须先取得用户确认：触及 Forbidden Changes ｜ 超出用户明确限定的文件范围 ｜ 跨越新的模块 / 服务 / API 边界 ｜ 新增依赖 ｜ 修改公共接口 ｜ 修改数据模型 / migration ｜ 修改认证 / 授权 / 安全逻辑 ｜ 导致 Risk Level 升级 ｜ 引入 Commit / Push / Deploy 等额外权限需求。

原则：Scope Expansion 必须显式记录，不静默扩张；也不对完全在已有授权范围内的微小扩张过度询问。被拒绝或暂缓的请求记录为 out-of-scope observation，不得以变通方式绕行实施。

5. 架构与证据原则

One Skill Entry · Two Core Tools · Replaceable Agent · Replaceable Model · Replaceable Environment

• Control Plane — 本 Skill（唯一入口）：Goal Contract ｜ 风险分级 ｜ Scope / Non-goals ｜ Tool Routing ｜ Validation Strategy ｜ Review Routing ｜ Finding Verification ｜ Completion ｜ Authorization ｜ Fallback。
• Core Tool Plane — CBM + OCR（固定核心）：职责见 §10，各定义一次，不重复实现。
• Replaceable Runtime Plane — 全部可替换：执行代理 ｜ 模型 ｜ Provider ｜ IDE ｜ Harness ｜ Shell ｜ 操作系统。示例仅是运行时可能性，不得将任何具体 Agent 写成框架依赖。
• Fact Layer — Source / Git / Build / Test / Runtime：最终事实依据。修改代码、验证完成、Review 通过、Commit、Push 是不同授权，每个阶段都必须有独立证据和明确边界。

6. Risk L0–L4（唯一风险轴）

先按当前证据选择风险等级；新证据显示风险更高时必须上调，不能仅按文件数量判定。风险决定 CBM 分析深度、验证强度和 Review Mode。

分类信号：Files changed（数量与集中度）｜ Module boundaries（跨边界 → L3 候选）｜ API changes（→ L3）｜ Data model changes（→ L3–L4）｜ Security impact（→ L4）｜ Production impact（→ L3–L4）｜ Dependency changes（L2 起步，影响 API 时上调）。

判定顺序：行为是否变更？（否 → L0）→ 单文件局部？（→ L1）→ 组件内多文件？（→ L2）→ 跨模块 / API / 数据结构？（→ L3）→ 支付 / 安全 / 迁移 / 关键生产路径？（→ L4）。硬性下限：安全、金额、权限、状态、数据兼容性问题不得判为 L1 及以下。 完整判定细则与每级执行要求见 references/execution.md。

风险判定输出完整评估，不输出裸等级（Risk Level: L2 这类单值声明不合格）：

Risk Assessment:
  Level:                 L0–L4
  Confidence:            HIGH / MEDIUM / LOW
  Evidence:              支撑判定的具体证据（结构、调用链、Diff、测试、依赖清单）
  Escalation Conditions: 触发升级的具体条件（如 "detect_changes 显示跨模块调用方 → 升 L3"）

• HIGH = 结构 / 调用链 / Diff 已实际确认；MEDIUM = 部分证据存在；LOW = 信息不足 → 保守工作流（按更高一档强度执行）+ 向用户说明。LOW 不得以"证据不足"为由降低强度。
• 升级：影响分析、Review Finding 或验证失败显示风险高于初判 → 立即重判，同步升级 CBM 深度、验证与审查强度；已完成步骤不回退重做，未开始步骤按新级别执行。
• 降级：仅当新证据明确显示初判过高（如"API 变更"实为私有方法改名）时允许，必须记录理由；不得为省审查而降级。
• 报告记录 Risk Level: 初判 → 终判 与 Confidence 变化。判定引擎失效（工具失效或无法在合理成本内取证）时同样走保守更高档并请求确认。

7. 核心生命周期（唯一主流程）

Goal
 ↓
Runtime Capability Gate（§9，记录实际工具面）
 ↓
Risk Adaptive Classification（L0–L4）
 ↓
CBM 修改前理解（L0/L1 跳过或 Lite；L4 先 Design Review）
 ↓
Implementation Context（收敛后交给执行代理）
 ↓
实现（最小必要改动，编辑前读取真实源码）
 ↓
第一次事实验证（Build / Test / Runtime）
 ↓
CBM 修改后影响分析 + 风险重评
 ↓
选择 Review Mode → 独立审查 → Finding 验证 → 修复 → 重新验证
 ↓
必要时 Re-review / 重新影响分析
 ↓
Runtime Verification（仅 L4）
 ↓
Goal 验收 → 状态沉淀（Commit / Push 仅在单独授权后）

按风险裁剪（裁剪只作用于步骤深度，不作用于行为红线——必需性自检与授权边界任何级别都保留）：

• L0：不进主链——Edit → 格式 / 渲染检查即可交付；发现实际行为变更立即重判，禁止以 L0 交付行为变更。
• L1：Context Scan（精确定位，不强制架构分析）→ Minimal Change → Target Validation；默认不做全局架构分析、全调用图、深度影响分析；行为变更默认做一次低成本审查（按变更性质决定，不按 Diff 是否存在决定）。
• L2：主链但 CBM 用 Lite 深度（符号定位 + 直接调用关系 + 源码验证 + 修改后影响分析）；需明确影响范围、直接调用方、Coverage Gaps、针对性测试与回滚说明。
• L3：完整主链 + 兼容性检查 + 明确回滚方案。
• L4：完整主链 + 两个强制门槛——实现前 Design Review（方案级评审，与代码 Review 分离，见 §11 降级阶梯）与实现后 Runtime Verification（运行级证据；仅单元测试通过不构成 L4 验收）。

主链各步要点：

1. 分析与计划：先建立 Repository Evidence，再定位真实调用路径和已有实现；产出精简 Implementation Context（见 §12）；区分图谱推断与源码事实；不顺手扩大范围。
2. 实现：只实现当前 Goal；执行代理默认不重新全仓库盲目探索、实现完不自己做一次完整终审、也不无条件接受 OCR 全部 Finding；编辑前读取足够原始源码；优先复用已有抽象；额外发现只记录不提前实现。
3. 验证：记录实际命令、结果、失败信息与未执行项及原因；先最小相关测试再按风险扩大；图谱和"代码看起来正确"不能替代构建和测试；环境导致的验证缺口记录 Environment Constraints（Issue / Impact / Workaround / Confidence Impact），与 Skill 逻辑失败严格区分，不得伪装成验证通过。
4. 修改后影响分析：基于真实 Git Diff 检查实际改了哪些符号、影响哪些调用方、是否突破 Scope、是否出现跨模块影响、风险是否需要升级。
5. 分离式 / 独立审查：与实现逻辑分离；Reviewer 不继续实现，也不只复述实现者摘要。独立性按 Review Independence 分级披露（§11）：FULL = Independent Review，PARTIAL = Context-separated Review，DEGRADED = Self-review。按 Blocker（不修复不能验收）/ Major（原则上必须解决，不采纳需明确证据）/ Minor（可修可记录）/ Suggestion（不得自动扩大当前 Goal）分级报告；Reviewer 不在同一步骤中直接修改代码。
6. Finding 验证与修复：禁止"审查说有问题 → 自动修复"；验证成立 → 执行代理修复（运行最相关测试 → 必要时模块 / 集成测试 → 检查 Git Diff）；验证不成立 → 标记误报并给出证据；属于后续改进 → 转入 Roadmap。修复扩大范围时重新做影响分析，风险升级时同步升级验证与审查强度。
7. 验收：Acceptance Criteria 逐项满足 + 验证证据可接受 + Blocker / Major 已解决（或按规则明确不采纳并留证）。
8. Git 授权：默认不 Commit、不 Push；细则见 §13。
9. 状态沉淀：默认只在 Completion Report 中报告状态（当前焦点、关键决定、验证状态、已知风险、Coverage Gaps、推荐下一 Goal）。写入仓库内的 ROADMAP.md / docs/status.md / .project-memory/* 等属于仓库修改——必须该文件在 Allowed Changes 内、或有对应写入授权（.project-memory/* 还须 memory_write 授权），不要把状态沉淀当成自动副作用。更新 Engineering Memory 时只记重要且难以从代码重新推导的知识，不记过程流水。

8. Evidence E0–E4（证据层级）

E0 = inference only          仅推断 / 未运行
E1 = source / static         源码阅读 / 图谱 / 静态检查
E2 = targeted tests          针对性测试 / 单元测试
E3 = integration / runtime   集成测试 / 服务启动 / 运行日志 / 容器执行
E4 = production-like         类生产演练 / 迁移演练 / 外部依赖实测

最低证据要求（低层级不能替代高层级验收）：

L0 → E1        L1 → E1/E2      L2 → E2
L3 → E2，优先 E3
L4 → E3；生产迁移 / 关键外部影响优先 E4

不满足最低 Evidence 时，不能把 Goal 标为完全完成——按实际层级记录并显式声明剩余风险（Decision: 有条件成立 / 不成立）。L4 Runtime Verification 接受的运行级证据（integration tests ｜ service startup verification ｜ container execution ｜ migration dry run ｜ runtime logs ｜ external dependency checks）与完整协议见 references/execution.md。

9. Fact Priority 与 Runtime Capability Gate

唯一事实优先级：

Runtime / Tests  >  Real Source  >  Git Diff  >  CBM Graph  >  Model Inference

• CBM 图谱不能证明代码运行正确。
• OCR Finding 不能自动证明 Bug 成立。
• LLM 推理不能替代 Test / Runtime。
• Finding 必须回到源码、Diff、测试或运行结果实证。

Runtime Capability Gate：每次任务开始时检查当前会话的实际工具面，而不是只看安装文件、配置或历史记录：

已安装 ≠ 已注册 ≠ 当前会话已暴露 ≠ 真实调用成功

Core Runtime Gate 至少记录：

Repository / Git: AVAILABLE / UNAVAILABLE
Implementation Agent capability: 当前宿主能否读改源码 / 运行命令
CBM: AVAILABLE / UNAVAILABLE
CBM Index: HEALTHY / STALE / PARTIAL / MISSING / UNKNOWN
OCR CLI: AVAILABLE / UNAVAILABLE
OCR Capability: MANAGED / DELEGATED / BOTH / NONE
Selected Review Mode: DELEGATED / DELEGATED + MANAGED / AGENT_INDEPENDENT_REVIEW / NOT_REQUIRED
Review Independence: FULL / PARTIAL / DEGRADED（本轮实际 Reviewer 记录）
Validation capability: Build / Test / Runtime 可用性
Framework Status: FULL / DEGRADED / UNKNOWN
Runtime Status: FULL / DEGRADED / BLOCKED
Project Intelligence Status: NO_REPOSITORY / EMPTY_PROJECT / UNINDEXED / INDEXING / READY / STALE / REFRESH_REQUIRED / BLOCKED
OCR Context Status: READY / BLOCKED_BY_CONTEXT / DEGRADED
Fallback: NONE / SOURCE_SEARCH_GIT_TESTS / DELEGATED_REVIEW / AGENT_INDEPENDENT_REVIEW

判定规则：

1. CBM：只有当前会话实际暴露了可明确归属于 codebase-memory-mcp 的工具并至少成功完成一次安全只读调用，才标 AVAILABLE。工具可用 ≠ 目标仓库已有可用索引——CBM 与 CBM Index 是两个独立状态。
2. OCR：ocr 命令存在 ≠ OCR AVAILABLE，必须真实调用成功（如 ocr version）。已配置可用 LLM Provider 且 provider 测试通过 → MANAGED；未配置 LLM 或明确使用 Delegation 工作流 → DELEGATED；两者皆可用 → BOTH；皆不可用 → NONE。不要因 Managed 不可用就把整个 OCR 记为 UNAVAILABLE。
3. CBM 副作用区分：只读工具可安全探测；index_repository / delete_project / manage_adr（写入）/ ingest_traces 有副作用，不得自动执行（见 §13）。完整 15 工具清单与副作用分类见 references/tools-and-troubleshooting.md。
4. 不根据文档、配置或旧会话补充未暴露的工具名称；未在当前会话实际暴露的工具不得假定存在。
5. CBM / OCR 任一不可用或能力受限时，走 §14 Fallback；能力缺失只改变证据获取方式，不降低验收标准。

Framework Status：REQUIRED 全部满足（读 Skill ｜ 读改源码 ｜ Git ｜ Build / Test / Runtime ｜ CBM ｜ OCR ｜ Context 隔离）→ FULL；CBM 或 OCR 临时不可用并走 fallback → DEGRADED——Fallback 能让 Goal 继续 ≠ 完整满足框架运行条件，长期无 CBM/OCR 的环境不得称为完整框架。OPTIONAL（额外 MCP / Reviewer Model / Observability）缺失不影响 FULL 定义。

Project Activation 与 Development Ready

$patchpilot project 是独立于 Runtime Bootstrap 的项目激活入口：它不编写业务代码，不替代 Goal Skill，不自动 Commit / Push，也不在未确认时创建或刷新 CBM 索引。其目标是把当前真实仓库从 UNINDEXED 推进到可开始 Goal 的 DEVELOPMENT_READY。

执行顺序：

解析 Git root / branch / commit / status
  → 检测源码（排除 .git、构建产物和空目录）
  → 只读检查 CBM Runtime、注册、当前会话暴露和已有 project
  → 生成 Project Plan（含 Git Baseline、索引动作、覆盖验证和 OCR Context）
  → 用户明确确认
  → 调用 index_repository（仅在确认后）
  → index_status / check_index_coverage / 只读图谱 smoke test
  → 准备 OCR Delegated Context
  → 输出 Development Ready 状态

状态语义：

• NO_REPOSITORY：无法解析 Git root；不得创建索引，OCR Context 为 BLOCKED_BY_CONTEXT。
• EMPTY_PROJECT：有效 Git 仓库但没有可分析源码；不得调用 index_repository。
• UNINDEXED：存在源码但 CBM 没有该仓库项目；只生成计划，不把猜测固化为 Ticket 或索引。
• INDEXING：用户已确认且索引操作正在进行；保存动作和可恢复状态。
• READY：索引健康、覆盖检查和只读图谱 smoke test 通过。
• STALE：已有项目但索引陈旧；只提示 Recommend refresh，不自动刷新。
• REFRESH_REQUIRED：结构或大范围变更使当前索引不足以支持本 Goal；必须在用户确认后刷新，否则降级并记录缺口。
• BLOCKED：用户未确认、索引失败或必要能力不可用；不得删除已有数据。

Runtime Status 只描述 Git / CBM Runtime / OCR Runtime；Project Intelligence Status 描述仓库知识状态；OCR Context Status 描述当前 Diff 是否可审查。没有 pending diff 时可记录 READY (no pending diff)，只有在实际 Review 请求缺少 Git / Changed Files / Diff Context 时才标 BLOCKED_BY_CONTEXT。三者均满足且 Git Baseline 已记录时，输出 Overall: DEVELOPMENT_READY，否则输出具体阻塞状态。

每个 Goal 在开始前记录 Git Baseline：repository_root、branch、current_commit、git_status；完成后记录 before_commit、after_commit（未 Commit 时为工作树状态）、Changed Files 和 Diff 摘要。Git 是范围和回溯证据，不等同于 Commit 授权。

10. CBM / OCR 职责边界

CBM（repository intelligence）

负责：架构 / 符号 / 调用关系理解 ｜ 修改前理解 ｜ 修改后影响分析 ｜ 结构性验证 ｜ Coverage Gaps 检查。
不负责：证明 Runtime 正确 ｜ 代替测试 ｜ 代替 Reviewer ｜ 自动修改代码 ｜ 决定最终验收。

OCR（review tooling）

负责：当前 Diff / 文件审查 ｜ Review Rules 与范围归一 ｜ Finding 生成 ｜ Managed / Delegated 审查路由。
不负责：替代 CBM 做全仓库结构理解 ｜ 替代测试 ｜ 自动证明 Finding 正确 ｜ 默认直接修代码。

职责分界（各定义一次）：CBM = 代码库级结构和影响关系；OCR 语义分组 = 当前 Diff 内相关变更如何共同审查。CBM 不做 OCR 的缺陷审查；OCR 不替代测试。

Repository Intelligence Policy

1. 真实仓库根目录：代码发现前先解析真实仓库根目录（优先 Git root）；不得把聊天生成目录、构建输出目录当 CBM 项目根。
2. CBM 是证据层，不是事实终点：图谱结果用于发现结构、候选符号、调用关系和影响范围；编辑前必须读取足够原始源码；关键结论必须由源码、Git 或运行结果验证。
3. 按需查询：陌生仓库先架构概览，再窄范围符号搜索、调用链查询和精确片段读取；已知小范围改动不强制全局架构分析。
4. 源码兜底（动态行为）：反射、动态导入、插件系统、DI 容器、配置驱动、SQL 字符串、模板、生成代码、外部服务、消息队列、数据库实际状态，默认不能只依赖 CBM——最终由原始文件、Git、配置、日志、测试或运行环境确认。
5. 软读取预算：初始直接读取的源码文件默认不超过 8 个；需要扩大范围时说明新增文件与 Goal 的关系；未变化文件避免重复完整读取。
6. 证据强度分级：计划和审查中分开标识图谱证据、源码证据、Git 证据、运行证据和未知范围；索引不足时不得输出"无影响""不存在""全部覆盖"等强结论。
7. Coverage Gaps 是一等状态：禁止"CBM 没找到 = 不存在"。重要否定结论必须先做覆盖检查（check_index_coverage 优先；不可用时回退源码、Git、文本搜索）；即使覆盖正常也只能表述为"未发现已知索引缺口"。
8. 影响 Review：跨模块、公共接口、数据模型、持久化格式、并发、安全边界改动，审查时应使用影响分析、关键调用链和测试证据；低风险单文件改动可跳过但须说明原因。

CBM Index & Read-only Policy

"只读分析"指不修改仓库内容、Git 状态和长期项目配置，不等于禁止所有本地缓存行为。

• 允许：查询现有索引状态 ｜ 用现有索引做只读图谱查询 ｜ 读仓库文件、Git 历史、diff、构建配置和测试结果 ｜ 在对话中输出分析与契约。
• 禁止：修改仓库文件 ｜ 修改 Git index、Commit、Push、建分支 ｜ 创建 / 更新 / 删除 ADR ｜ 修改 CBM 管理的 MCP 配置、Hook、AGENTS.md 管理块 ｜ 修改 CBM 全局配置与 watcher 策略。
• 索引授权：用户仅要求只读分析时优先用已有健康索引；索引缺失 / 过期时先说明建立或刷新的需求与替代方案；获明确授权后可执行索引操作但不得顺带改其他配置；未授权时用 Git + 文本搜索 + 定向读取降级。

Decision Chain:
解析 Git root → 确认 CBM 可用性 → 确认索引状态
  ├─ 健康：使用图谱建立 Repository Evidence
  ├─ 过期：说明刷新需求；获授权则刷新，否则标记限制并降级
  ├─ 覆盖缺口：对缺口路径定向读取源码或文本搜索
  ├─ 未索引：说明需求；未获授权则降级
  └─ 不可用：Git + rg/grep + 定向 Read + 测试

降级后仍遵守范围、读取预算、证据分级和 Review 规则，不得退化为无目的全仓库扫描。

CBM Core Usage（最小工具映射与三阶段）

仓库架构概览         → get_architecture      符号与结构定位    → search_graph
调用链与上下游       → trace_path            精确源码片段      → get_code_snippet
索引内文本搜索       → search_code           自定义结构查询    → query_graph
修改后影响分析       → detect_changes        索引覆盖检查      → check_index_coverage

使用原则：先窄后宽、先结构后原文、先候选后验证；不为"完整"机械调用全部工具。

• 阶段一 Understand（修改前理解）：找到正确修改点、确定调用关系与影响范围、发现已有实现；产出 Repository Evidence 与 Implementation Context。
• 阶段二 Impact（修改后影响分析）：实现并完成第一次事实验证后，基于真实 Git Diff 检查实际影响面、Scope 突破与跨模块影响。detect_changes 只有同时满足「CBM AVAILABLE ｜ 目标仓库已被识别 ｜ 索引状态可用 ｜ 变更在覆盖内或缺口已记录」才优先调用；不自动 index_repository；中高风险 Goal 不得因 detect_changes 不可用就跳过影响分析（git diff + 调用方检查替代）。
• 阶段三 Verify（Finding 结构验证）：用 trace_path / search_graph / get_code_snippet / check_index_coverage 验证 Finding 声称的结构关系，再回到源码确认（统一走 §7 第 6 步）。

OCR Review Policy

OCR 是确定性工程 × Agent 混合的审查 CLI，不是"另一个 LLM 看一眼 Diff"。

Review Routing：

L0 → NOT_REQUIRED by default（非行为变更——文档 / 注释 / 纯格式化——即使产生 Git Diff，也不因「存在 Diff」自动升 L1；Diff 中出现行为代码、配置行为、依赖、接口或运行逻辑变化时，必须重新执行 Risk Assessment 并至少按 L1 处理）
L1 → OCR DELEGATED / low-cost Review
L2 → OCR DELEGATED
L3 → DELEGATED baseline + 评估 Managed escalation
L4 → DELEGATED baseline + 从严评估 Managed escalation

Managed Escalation 触发器：

• SUPPORTED（可自动建议升级）— Implicit Contract Risk：Diff 影响多模块共享的隐式契约 + 调用方默认某 helper 提供安全保证 + 现有测试无法证明边界行为 + blast radius 跨模块 + 需要不同模型视角。示例类型：Redaction 边界 ｜ 共享 serializer ｜ 共享 lifecycle helper ｜ 共享持久化变换 ｜ 跨模块校验契约。
• PLAUSIBLE（只可建议，不得自动强制）：Concurrency / Async ｜ State Transition ｜ Public API ｜ Persistence ｜ Security/Auth ｜ Large Blast Radius ｜ Runtime Magic。

L3 ≠ Always Managed：Managed 是高成本增量 Reviewer，受控验证结论为双臂互补、Managed 非超集。决策步骤：先 Delegated baseline → 评估触发器 → SUPPORTED 命中 = RECOMMENDED；仅 PLAUSIBLE = OPTIONAL / USER-COST-AWARE；无触发器 = Delegated-only acceptable。升级前记录：Why / Trigger / Expected Value / Provider / Model / Cost Authorization。Managed 不可用记录 BLOCKED_BY_CONFIGURATION 继续 Delegated，不阻断 Goal。--effort 是 Review 轮数（low=1 / medium=2 / high=3），是 review 偏浅时最便宜的质量杠杆，不要所有任务统一 high。

Finding Merge 与分类（多 Reviewer 结果合并）：

Delegated + Managed Findings → 逐条 Verification → Deduplication → Final Result

两种 Reviewer 的结果是 union of evidence，不是 Managed overrides Delegated。分类：TRUE_ACTIONABLE ｜ NON_ACTIONABLE_OBSERVATION ｜ FALSE_POSITIVE ｜ PRE_EXISTING_TRUE_FINDING ｜ NON_GOAL ｜ DUPLICATE ｜ UNCERTAIN。统计时分离 Current-Diff Actionable 与 Pre-existing True Finding，后者不计入"本次实现引入缺陷"。

审查纪律：

• Preview 先行：正式 Review 前确认文件范围、过滤结果与排除文件（Preview 不消耗正式 Review Token）；范围异常先修正 Scope / Rules，不要直接继续。
• Review Context：只传 Goal、Acceptance Criteria、Scope / Non-goals、实际变更符号、关键影响链、Invariants、实际验证结果、Coverage Gaps、Review Focus——不把完整开发会话传给 Reviewer。
• Token Budget：按风险档位定预算（L1 小 / L2 中 / L3–L4 大），不写死未经真实项目验证的固定数值；Completion Report 记录实际用量，拿不到精确数字不伪造。
• Reviewer 工具白名单：默认只向 Reviewer 开放只读 CBM 能力（detect_changes / trace_path / check_index_coverage / get_code_snippet / search_graph）；默认禁止暴露 index_repository、manage_adr、delete_project、ingest_traces 及任何修改配置 / Commit / Push 能力；query_graph 默认不进入 Reviewer Profile（仅 L3/L4 复杂结构问题按需开放）。Reviewer 发现索引过期时报告问题返回主流程，不自动刷新索引。
• Diff First：发现潜在问题 → 判断影响 → trace_path → 必要时读关键源码 → 判定成立；错误路径是"开始审查 → 扫描整个架构 → 最后才回到 Diff"。
• Session 与 Re-review：Managed 模式记录 Review Session，重要修复后用 Session Compare 对比 new / persisting / resolved / not reviewed（按 path + category + 片段匹配，不依赖行号）。必须 Re-review：Blocker / Major 修复 ｜ 范围明显扩大 ｜ L3/L4 代码重新实现。可跳过：首次无重要 Finding 且代码未变。Delegated 模式没有 Session 能力时用 Goal 自身 Review 状态替代，不伪造 OCR Session。

11. Review Independence（统一模型）

同一模型同时用于 Code Review Independence 与 Design Review Independence：

FULL      独立 Reviewer 模型 + 独立 Review Context（OCR Managed 使用独立 Provider/模型）
PARTIAL   同一宿主模型 + 独立 Review Context / Session + Diff First
          （OCR Delegated 属于 PARTIAL，称 Context-separated Review，不得称为真正的 Independent Review）
DEGRADED  实现上下文直接自审，无逻辑隔离；必须在 Completion Report 显式披露

L4 Design Review 降级阶梯（实现前的方案级评审，按顺序取可用的最高档）：

1. Human reviewer
2. Truly separate reviewer / model
3. Managed review capability
4. Context-separated review
5. Self-review fallback

若只能 DEGRADED（第 5 档）：不得伪装成独立 Design Review；显式提高运行时验证要求；在最终报告披露该限制；对生产关键 / 安全敏感 Goal，证据不足时应返回 BLOCKED，而不是硬标 COMPLETED。

12. Context Boundaries（Token 收敛边界）

Implementation Context（CBM → 执行代理）

禁止把完整 CBM 输出、完整架构报告、大量源码直接塞给执行代理。只允许：Goal / 目标符号 / 关键文件 / 关键调用链 / 直接影响对象 ｜ 必须保持的 Invariants ｜ 允许修改范围 / Non-goals ｜ Coverage Gaps / 建议验证项。执行代理必须读取真实源码后再实施。

Review Context（Goal + CBM + Validation → Reviewer）

只传：Goal、Acceptance Criteria、Scope / Non-goals、实际变更符号、关键影响链、Invariants、实际验证结果、Coverage Gaps、Review Focus。不把完整开发会话传给 Reviewer——目的是保持审查相对独立。同样适用于 Delegated 的独立 Review Agent。

Fix Context（Reviewer → 执行代理）

只包含：Finding、严重度、相关文件 / 代码、为什么成立、必要的调用关系证据、必须保持的 Invariants、推荐重新执行的验证。不把整个 OCR Session 或完整审查历史塞回执行代理。

统一原则：传结论 + 关键证据 + 证据位置，不传整个探索历史。 目标是每个通过验收的 Goal：更少无效读取 + 更少重复探索 + 更少错误修改 + 更低总 Token；不为省 Token 跳过关键源码、完整 Diff、关键错误输出、测试和 Runtime 证据。

13. Scope / Authorization Hard Boundaries

默认禁止自动执行，仅用户明确授权后执行：

git commit / git push / 创建或切换远程分支
发布 / 部署 / 删除资源
安装系统级或全局依赖
修改宿主 Agent 全局配置 / 其他 Skill / Agent 定义
写入 API Key / token / secret
创建或删除 CBM index
修改用户未授权文件
创建或更新 Engineering Memory

• 不得从"帮我修复"推断"可以 commit / push / deploy"。
• 授权 Commit 不自动包含 Push；授权 Push 不推断可创建额外 Commit 或改写历史。
• Commit 前再次确认变更范围和验证状态；Push 前确认目标分支、远端和授权。
• 不自动创建远端资源（Issue / PR / Release / 云资源）。
• 不修改 CBM 管理的 MCP 配置、Hook、AGENTS.md 管理块；不将图谱结论描述为完整源码事实；不为低风险小任务机械执行完整架构审计。
• OCR Finding 不自动触发修改；必须先验证再修复。不自动配置 OCR Provider / API Key；API Key 不写入 Skill、项目、日志、Review Context 或报告。
• 不伪造 OCR Session、Token 数字或能力状态；未执行的检查写 NOT RUN / NOT USED / UNAVAILABLE / NOT REQUIRED，不写 PASS。
• 不确定性会实质改变范围、风险、兼容性或方案时，先向用户说明并取得方向。

14. Fallback 核心规则

任何辅助工具不可用都不能让 Goal 流程瘫痪；降级只改变证据获取方式，不降低验收标准。

长期无 CBM / OCR 的环境是 Framework Status: DEGRADED，不因存在 fallback 而称为完整框架。降级后仍遵守范围、预算、证据分级与 Review 规则。

15. Completion Gate

Goal 终态只允许五种：

COMPLETED  |  PARTIAL  |  BLOCKED  |  ANALYSIS_COMPLETE  |  REVIEW_COMPLETE

COMPLETED 必须同时满足：

1. Goal Acceptance Criteria 已逐项核对；
2. Diff 在 Scope 内，无未经授权的副作用；
3. Required Evidence Level 达到 Risk Level 对应的最低层级；
4. Required Review Gate 已完成或按规则明确降级并披露；
5. Findings 已实证或关闭（Blocker / Major 已解决或留证不采纳）；
6. 已披露 Coverage Gaps / Review Independence / Tool limitations。

Completion Report（五段式）

分两级：Default（默认）与 Extended（L3/L4 ｜ Managed Review ｜ 复杂降级 ｜ 安全 / 数据 / 迁移 ｜ 用户要求时使用，保留全部诊断字段）。未执行的检查必须写 NOT RUN / NOT USED / UNAVAILABLE / NOT REQUIRED / NOT APPLICABLE，不能伪装成 PASS。L0 允许只输出前两段。

## Change Summary
Goal
Result: COMPLETED / PARTIAL / BLOCKED / ANALYSIS_COMPLETE / REVIEW_COMPLETE
Risk Level: L0–L4（初判 → 终判；上调须说明触发信号）
Framework Status: FULL / DEGRADED

## Change Contract
Goal / Scope · Allowed Changes / Non-goals · Forbidden Changes

## Implementation
Changed Files
CBM Evidence（实际调用的工具与结论）
Post-change Impact

## Validation
Risk Assessment（Level + Confidence，初判 → 终判）
Evidence Level（E0–E4 实际达到层级）
Environment Constraints（Issue / Impact / Workaround / Confidence Impact；无则 NONE）
Runtime Evidence（实际运行级证据；无则 NOT RUN + 原因）
Decision（验收成立 / 不成立 / 有条件成立，依据 = 最低 Evidence Level 是否达成）
Tests / Commands
Review / Findings / Fixes（Blocker / Major / Minor / Suggestion 数量与验证结果，含误报）
Review Independence: FULL / PARTIAL / DEGRADED
Coverage Gaps / Residual Risks
Commit: NOT AUTHORIZED / AUTHORIZED_NOT_EXECUTED / EXECUTED / FAILED
Push:   NOT AUTHORIZED / AUTHORIZED_NOT_EXECUTED / EXECUTED / FAILED

## Memory Update
Updated:（.project-memory/ 实际变更；无变更写 NONE）
Next

Extended 版在 Default 基础上增加：Tool Availability 明细（CBM Index 状态 / OCR Capability / OCR Managed LLM / Selected Review Mode / Managed Escalation Trigger / Fallback）、OCR Preview 状态、OCR Review Session / Effort / Token Usage、Finding Verification 与 Re-validation 明细、OCR Re-review 与 Session Comparison、Index Action（NOT CALLED / CALLED WITH AUTHORIZATION / FAILED / UNAVAILABLE）、Known Limitations、Residual Risks。Delegated 模式：OCR Managed Token Usage: NOT REQUIRED，Session Comparison 可为 NOT APPLICABLE。Commit 与 Push 始终分开。

16. References（按需加载，不在每次 Goal 加载）

• references/execution.md — 执行细则：协作风格 / L0–L4 风险模型完整细则与每级执行要求 / Mode × Risk 组合矩阵 / Change Boundary Contract / Evidence & Validation 与 L4 Runtime Verification 协议 / Safe Degradation。
• references/engineering-memory.md — .project-memory/ 六文件职责与模板、memory_write 授权、Trust Metadata、条目生命周期与治理、预算与索引。
• references/tools-and-troubleshooting.md — CBM 15 工具清单与副作用分类、安装验证清单、沙箱 DACL 与 git 所有权排障、OCR 能力等级与 CLI 速查、FAQ、反模式。
• references/maintainers.md — 维护者专属（运行时不加载）：版本策略、发布清单、包卫生、自检清单、验收用例核对表。
• examples/ — 四种入口模式的完整真实案例。

核心规则只定义一次：主文件负责决策，references 负责展开，examples 负责演示。低频 CLI / upstream / maintenance 细节按需查阅；运行时以当前实际工具面为准。

17. Capability Doctor and Bootstrap（CBM + OCR）

PatchPilot 本体安装不等于 CBM / OCR 已可用。当前宿主没有原生 patchpilot CLI 时，以下两个入口由 Skill 等价执行：

$patchpilot doctor
$patchpilot bootstrap
$patchpilot project

17.1 doctor：只读能力检测

doctor 不安装依赖、不改宿主配置、不创建或删除索引、不写凭证。它必须只依据当前会话实际暴露的工具和真实调用结果，输出以下能力矩阵：

最终只允许输出：

Framework Status: FULL
Framework Status: DEGRADED

CBM 检测顺序：确认安装 → 确认宿主注册 → 确认当前会话暴露的完整工具名称 → 使用实际 schema 调用最小 smoke test（优先 search_graph、trace_path、get_code_snippet）→ 判断索引状态。仅存在包、配置或历史记录不能判定 PASS；未授权不得调用 index_repository、删除项目或修改 MCP 配置。

OCR 检测顺序：确认实际 CLI / MCP / API 入口 → 确认项目读取权限 → 在一次性 fixture 或无副作用 diff 上执行最小独立审查 → 验证结构化结果和 Reviewer 独立性。普通 Agent 自审不得标记 FULL；只能使用 delegated / independent agent review 时标记 OCR Status: DEGRADED 和 Reviewer Independence: DEGRADED。

17.2 project：项目激活与 Development Ready

project 只处理项目级激活，不重复执行 Runtime Bootstrap。它先运行 doctor 的只读能力检查，再检查 Git root、源码、CBM project/index 状态、Coverage 和 OCR Context，并输出 Project Plan。计划至少列出：

repository_root / branch / current_commit / git_status
source_detected / existing_cbm_project / index_status
将调用的 index_repository 及其范围
覆盖验证、OCR Context 预期状态、回滚方式

用户明确确认前，project 只能输出计划并保持 UNINDEXED / BLOCKED；确认后才可调用 index_repository。索引完成必须依次执行 index_status、check_index_coverage 和安全只读图谱 smoke test，失败则输出 DEGRADED / BLOCKED，不得删除已有数据或伪报 READY。已有健康项目重复运行时输出 Already Ready、Actions: 0，不得重复索引、注册或创建备份。

当项目已解析 Git root、源码可分析、CBM Intelligence 为 READY、Git Baseline 已记录且 OCR Delegated Context 可准备时，输出：

Runtime: FULL / DEGRADED / BLOCKED
Project: DEVELOPMENT_READY / PROJECT_SETUP_REQUIRED / BLOCKED
CBM Intelligence: READY / UNINDEXED / STALE / BLOCKED
Git Baseline: READY / MISSING
OCR Context: READY / BLOCKED_BY_CONTEXT / DEGRADED

project 不编写业务代码，不替代 Goal Skill；当前宿主使用 @goal-driven-development-cbm 承接 Understand、Impact、Implementation、Validation 和 OCR Review。若后续提供合并的 @goal-driven-development-cbm-ocr，仅替换路由目标，不改变本激活协议。无 Git、空仓库或未确认索引时，保留相应状态并停止在项目激活阶段。

成功激活时使用精简输出：

Runtime:
  Git: READY
  CBM: READY
  OCR: READY
Project:
  Repository: READY
  CBM Intelligence: READY
  Git Baseline: READY
  OCR Context: READY
Overall: DEVELOPMENT_READY
Next: @goal-driven-development-cbm

Project Activation 的停止条件：Runtime Regression、Doctor、Project Activation、CBM Index、Coverage、Git Baseline、OCR Context、Idempotency 和 Security Boundary 均为 PASS 后才可输出 Overall: DEVELOPMENT_READY；任一未通过都必须保留具体 DEGRADED / BLOCKED 状态。

17.3 bootstrap：显式安装引导

bootstrap 先执行 doctor，再为 MISSING / MISCONFIGURED 项生成安装计划。安装计划必须先展示：组件、来源、版本、目标范围、将修改的文件、变更前状态、变更后状态和回滚方式；用户明确确认后才可执行。

安装优先级固定为：

已安装 → 复用
已安装但未注册 → 只注册
缺失 → 生成计划
用户确认 → 安装 / 注册
安装后 → 重新 doctor → smoke test

配置范围按 project scope → user scope → machine-global scope 选择。不得静默安装第三方依赖、修改宿主全局配置、写 API Key / token / secret、覆盖已有 CBM / OCR 配置或创建 / 删除索引。Commit、Push、发布和部署授权仍然独立。

如果用户未确认某一项安装或配置变更，bootstrap 必须停在 BLOCKED，而不是代替用户执行；可继续完成不需要该授权的只读检测。

17.4 报告与降级

完成 doctor 或 bootstrap 后，在用户指定的项目输出根目录生成：

PATCHPILOT_INSTALL_REPORT.md
PATCHPILOT_DOCTOR.json

JSON 至少包含：

{
  "patchpilot": "PASS",
  "cbm": "PASS|DEGRADED|UNAVAILABLE|BLOCKED",
  "ocr": "PASS|DEGRADED|UNAVAILABLE|BLOCKED",
  "git": "PASS|UNAVAILABLE",
  "runtime_status": "FULL|DEGRADED|BLOCKED",
  "project_intelligence_status": "NO_REPOSITORY|EMPTY_PROJECT|UNINDEXED|INDEXING|READY|STALE|REFRESH_REQUIRED|BLOCKED",
  "ocr_context_status": "READY|BLOCKED_BY_CONTEXT|DEGRADED",
  "development_ready": true,
  "git_baseline": {},
  "framework_status": "FULL|DEGRADED",
  "smoke_tests": {},
  "configuration_changes": [],
  "rollback": []
}

CBM 不可用时回退到 git + rg/grep + targeted source reading + tests；OCR 不可用时依次尝试 Managed OCR、Delegated OCR、Independent Agent Review。回退只改变证据获取方式，不降低验收标准，也不得将 DEGRADED 宣称为 FULL。

17.5 Bootstrap / Project 回归场景

以下场景是入口契约，执行结果必须写入 PATCHPILOT_DOCTOR.json 的 smoke_tests：

每个场景都必须区分“已安装、已注册、当前会话已暴露、真实调用成功”；未执行的检查写 NOT RUN，不得伪造通过。