feat: 初始提交

docs/prompts/README.md

@@ -0,0 +1,295 @@
+# Prompts
+
+面向 AI 大模型的执行型提示词集合。每份提示词都应能被单独复制使用，并驱动 AI 以一致的方式完成收集、分析、确认、执行和收尾。
+
+## 提示词
+
+| 文件                                                   | 用途                                                                      |
+| ------------------------------------------------------ | ------------------------------------------------------------------------- |
+| [prompt-smart-merge.md](prompt-smart-merge.md)         | 批量合并 `dev*` 分支到目标分支，含规则探测、依赖分析、冲突处理、安全回退  |
+| [prompt-proposal-review.md](prompt-proposal-review.md) | 审查 fast-drive design/tasks 与讨论、实际状态、OpenSpec workflow 的一致性 |
+| [prompt-apply-review.md](prompt-apply-review.md)       | 审查 apply 后实际产物、验证、design/tasks 的一致性，并补齐遗漏或回写文档  |
+
+## 边界说明
+
+本目录为 AI 大模型执行型提示词资产，不属于常规用户文档或开发文档流。文档影响分析不覆盖本目录内容。
+
+## 设计目标
+
+从现有提示词提炼出的共同目标：
+
+- 面向执行，不面向讲解
+- 先收集证据，再做判断
+- 先计划和确认，再做有副作用的修改
+- 对缺失信息、规则冲突、上下文不足有降级路径
+- 对删除、重写、提交、回退、推送等高风险动作有明确授权边界
+- 执行后必须复核，形成闭环
+
+## 命名规则
+
+文件名格式：`prompt-{action}.md`
+
+- `{action}` 使用明确、可搜索、无歧义的英文短语
+- 用连字符连接，不使用缩写、代号或过泛词
+- 优先体现动作和对象，如 `smart-merge`、`spec-review`、`apply-review`
+
+## 通用骨架
+
+大多数提示词应遵循以下结构；按任务类型增删章节，但顺序尽量保持一致：
+
+```md
+一句话描述任务目标
+
+## 约束
+
+## 1. 收集 / 准备
+
+## 2. 分析
+
+## 3. 报告 或 计划（用户确认）
+
+## 4. 执行（用户确认）
+
+## 5. 清理 / 收尾
+```
+
+适用方式：
+
+- 审查型：`收集 → 分析 → 报告 → 计划 → 执行 → 收尾`
+- 执行型：`准备 → 分析 → 计划 → 执行 → 清理`
+- 纯报告型：可省略执行，但仍要保留“信息不足时如何降级”和“结果如何输出”
+
+## 编写原则
+
+### 1. 面向 AI，不写背景说明
+
+- 不写业务背景、适用场景、周期性说明、方法论阐释
+- 不写“为什么这么做”的长解释，直接写成规则或步骤
+- 不写示例输出模板，除非输出格式本身就是约束的一部分
+
+### 2. 证据先于结论
+
+- 明确列出需要读取的文档、代码、测试、配置、命令结果
+- 能并行的步骤明确写“并行”
+- 默认优先使用当前会话信息、现有文档和仓库规则
+- 只有在无法定位对象、范围或规则时，才引导 AI 向用户提问或运行补充命令
+- 不要求 AI 无差别全量扫描整个仓库；先建立索引，再做定向读取
+
+### 3. 约束集中声明
+
+- 全局不可违反的规则统一放在 `## 约束`
+- 不在后续步骤反复重复同一条规则
+- 约束优先写边界、禁令、授权条件、同步要求、非目标
+
+常见约束类型：
+
+- 只允许修改哪些对象，不允许修改哪些对象
+- 是否默认按某个 workflow 执行
+- 是否以代码、文档、讨论或用户确认为准
+- 何时必须使用提问工具确认
+- 删除、重写前是否必须备份
+- 改动后是否必须同步 README、测试、变更文档
+
+### 4. 计划与执行分离
+
+- 分析阶段只产出问题、风险、候选动作，不直接修改
+- 执行前必须先给出计划或批次方案
+- 批次计划必须能让用户看懂“改什么、为什么、影响什么、如何验证”
+- 用户确认执行，不等于授权所有危险动作；额外高风险动作要单独确认
+
+### 5. 闭环优先
+
+- 执行后必须重新读取受影响对象并复核
+- 对代码修改要说明测试或验证方式
+- 对文档修改要检查相关文档之间是否同步一致
+- 收尾时要列出修改文件、备份文件、验证结果和残留风险
+
+## 各章节写法
+
+### 目标句
+
+第一句只做三件事：
+
+- 说明任务对象
+- 说明最终目标
+- 说明执行方式或范围
+
+要求：
+
+- 一句话写完
+- 不写背景铺垫
+- 尽量包含最终产物，如“生成计划”“回写文档”“整理稳定规范”
+
+### 约束
+
+推荐写法：
+
+- 作用域边界：改什么，不改什么
+- 真相来源优先级：代码 / README / spec / 讨论 / 用户确认
+- 风险动作边界：删除、重写、提交、推送、回退、stash、merge 等
+- 同步要求：测试、README、变更文档、现有 spec 是否要同步
+- 降级规则：信息不足时如何处理
+
+避免：
+
+- 在约束里塞步骤顺序
+- 同一规则在约束和执行里重复出现多次
+
+### 收集 / 准备
+
+要明确三类内容：
+
+- 读什么
+- 是否并行
+- 无法确定时如何补充定位
+
+推荐做法：
+
+- 先读仓库规则来源，如 `README.md`、配置、架构文档、近期提交、任务入口
+- 先读直接相关 artifacts，再扩展到相关代码和测试
+- 需要探测时，要求 AI 先探测再决定，不把仓库结构写死在提示词里
+
+### 分析
+
+分析部分优先使用表格表达维度、优先级和判定规则。
+
+推荐包含：
+
+- 优先级或维度表
+- 差异分类规则
+- 风险分级规则
+- 是否进入待确认清单的判定条件
+
+常见分析模式：
+
+- `P0 / P1 / P2 / P3` 优先级
+- “过时 / 重复 / 冲突 / 错位 / 命名 / 格式” 维度
+- “文档要求未实现 / 代码修补未回写 / 双方冲突待确认” 差异分类
+
+### 报告 / 计划
+
+这是现有提示词最稳定的共性区块，建议固定包含：
+
+- 问题总览表
+- 逐项分析
+- 待确认清单
+- 分批执行方案
+- 预期结果或目录结构
+
+若进入计划阶段，必须写清：
+
+- 改哪些文件或对象
+- 动作类型：删除、重命名、迁移、合并、拆分、补充、回写、修复
+- 修改原因
+- 预期影响
+- 验证方式
+
+### 执行
+
+执行部分要强调可操作性：
+
+- 明确顺序执行还是可并行执行
+- 明确每批执行前是否确认
+- 明确删除、重写、回退前是否要备份或创建锚点
+- 明确执行后最少要复核哪些点
+
+推荐写法：
+
+- “逐批执行”或“逐项执行”
+- “每批执行后重新读取受影响文件并复核”
+- “若涉及删除或重写，先创建备份文件 `{file}.bak.{timestamp}`”
+
+### 清理 / 收尾
+
+收尾要输出结果，不只说“完成”。
+
+建议包含：
+
+- 修改文件清单
+- 备份文件清单
+- 测试 / 构建 / 验证命令与结果
+- 文档同步摘要
+- 残留问题、未验证项、待确认事项
+
+## 交互与安全规范
+
+### 必须确认的动作
+
+以下动作默认都要在提示词中要求 AI 使用提问工具确认：
+
+- 删除文件或目录
+- 重写文件
+- 创建或恢复 stash
+- 回退、reset、revert、abort
+- 合并提交、推送、删分支、删远端分支、删 tag
+- 任何会改变工作区现场且用户未明确授权的操作
+
+### 授权边界要写清
+
+提示词要明确区分：
+
+- “确认当前计划”
+- “确认执行当前批次”
+- “确认某个具体危险动作”
+
+不要把这些授权混为一谈。
+
+### 回退路径要提前写好
+
+对高风险流程，提示词应提供至少一种回退机制：
+
+- 备份文件
+- 安全锚点 tag
+- `abort` 路径
+- 终止后的现场说明
+
+## 表达与格式
+
+- 优先使用表格表达规则、维度、状态、输出项
+- 列表优于段落
+- 每句话只写一条指令
+- 用 `{占位符}` 表示需要 AI 或用户填入的参数
+- 步骤编号使用 `## 1.`、`## 2.`，不用“第 X 步”
+- 信息展示遵循“概览 → 详情 → 原始数据”
+
+## 仓库适配规则
+
+- 若仓库文档已经定义命令、目录、提交格式、包管理器、工作流，提示词必须先遵守仓库文档
+- 若仓库未定义，再允许 AI 根据脚本、清单文件、近期提交历史推断
+- 不把当前仓库的偶然路径结构、命令名、分支名写死到所有提示词中
+- 只有当提示词本身就是为当前仓库的特定流程编写时，才写入仓库专属术语和路径
+
+## 反模式
+
+以下写法应避免：
+
+- 让 AI 一上来就全仓库无差别扫描
+- 在未分析前直接要求修改
+- 把代码现状直接当成唯一真相
+- 把历史变更文档直接当成稳定规范来源
+- 用抽象表述代替可执行动作
+- 把多个危险动作打包成一次默认授权
+- 没有备份、没有锚点、没有终止路径
+- 只要求“完成修改”，不要求复核和收尾
+
+## 编写检查清单
+
+编写完一份提示词后，至少自检以下问题：
+
+| 检查项           | 说明                                              |
+| ---------------- | ------------------------------------------------- |
+| 目标是否单句明确 | 是否能一眼看出任务对象、目标和范围                |
+| 约束是否集中     | 全局规则是否只在 `## 约束` 中声明                 |
+| 数据源是否具体   | 是否明确读哪些文档、代码、测试、命令结果          |
+| 是否先分析再执行 | 是否存在独立的分析和计划阶段                      |
+| 是否有确认节点   | 高风险动作前是否要求提问工具确认                  |
+| 是否有降级路径   | change 不明、规则不明、上下文不足时是否有处理方式 |
+| 是否可操作       | 是否给出命令、工具、路径或结构化动作              |
+| 是否可验证       | 执行后是否定义复核或测试方式                      |
+| 是否能收尾       | 是否要求输出修改清单、备份、验证结果、残留风险    |
+
+## 维护原则
+
+- 新增提示词前，先判断能否复用现有提示词的结构和术语
+- 修改提示词时，优先提炼共性，不为单次场景堆特例
+- 若某条规则已在多个提示词中稳定出现，应回收进本 README，作为统一编写规范

docs/prompts/prompt-apply-review.md

@@ -0,0 +1,179 @@
+审查 OpenSpec apply 完成后以及后续手动修补后的实际变更，判断实际产物、验证结果和变更文档是否与 `design.md` source of truth 一致，识别偏离、漏记和可优化点，并将确认后的实际变更同步回变更文档，按以下流程执行。
+
+## 约束
+
+- 先审查再修复；未经用户确认，不修改实际产物或变更文档
+- 默认按 `fast-drive` workflow 审查；识别 change 后先确认 `schemaName`；若实际 schema 不同，说明差异，仅对实际存在的 artifacts 做审查
+- 在 `fast-drive` workflow 下，核心 artifacts 是 `design.md` 和 `tasks.md`；不要要求存在 `proposal.md` 或 `specs/*.md`
+- 在 `fast-drive` workflow 下，`design.md` 是 scope、requirements、decisions、guardrails、execution direction 和 verification expectations 的 source of truth，`tasks.md` 是 apply 进度和验证闭环的 tracking 文件
+- 禁止同步或修改 `openspec/specs/` 下的主规范；若实际 schema 包含 `specs/*.md`，也只允许修改本次 change 目录下实际存在的 spec artifacts，主规范同步属于 archive 阶段，不在此提示词范围内
+- 优先使用当前会话中的执行说明、验证结论、手动修补记录和已生成的变更文档；仅在无法明确 change、`schemaName`、改动范围或修补来源时，再用提问工具或 OpenSpec 命令补充定位
+- 不要因为实际产物已经存在就自动以实际产物为准；先判断差异属于“design 要求未完成”、“验证后新增修补”、“合理落地细化”还是“意外偏离/回归”
+- 每批实际产物或文档修改执行前用提问工具获得用户确认
+- 删除/重写前用提问工具获得用户确认，并先备份原文件为 `{file}.bak.{timestamp}`
+- 若修改实际产物涉及新行为、流程、接口、内容、数据、配置、责任边界或用户可见结果，同步更新验证材料、相关变更文档和必要的文档/沟通材料
+
+## 1. 收集
+
+读取约束：
+
+- 直接使用 Read 工具并行读取文件，禁止使用 subagent/Task 工具做文件读取和内容转发
+- 不原样输出文件内容，仅在步骤 2 输出审查结论
+
+分步收集：
+
+a) 先并行读取核心入口和配置，确定范围：
+
+- 本次 change 的 `design.md`
+- 本次 change 的 `tasks.md`
+- workflow context/configuration，例如存在时读取 `openspec/config.yaml`
+- 若可定位到 schema，读取对应 schema；`fast-drive` 下优先读取 `openspec/schemas/fast-drive/schema.yaml`
+
+b) 从 `design.md` 提取审查基准：
+
+- `Context`
+- `Discussion Notes`
+- `Requirements`
+- `Goals / Non-Goals`
+- `Execution Guardrails`
+- `Affected Areas`
+- `Decisions`
+- `Execution Plan`
+- `Verification Plan`
+- `Risks / Trade-offs`
+- `Open Questions`
+
+c) 从 `tasks.md` 提取任务状态、已完成项、未完成项、验证任务和文档/沟通任务；重点记录所有已标记完成的 `- [x]` 或等价完成状态。
+
+d) 获取实际改动范围：若在版本控制工作区中，优先使用 `git diff --name-only`、`git diff --name-only --cached`；若工作区已干净或不适用版本控制，再结合 `design.md`、`tasks.md`、验证记录和执行记录反推。
+
+e) 并行读取实际改动范围、`Affected Areas`、`Execution Plan`、`Verification Plan` 涉及的实际产物、参考材料、验证材料、流程说明、配置、文档或沟通材料。
+
+f) 收集当前会话中与本次变更相关的执行说明、apply 过程中的偏离、验证失败、手动修补原因、验证命令或检查结果、待确认事项。
+
+g) 若实际 schema 不是 `fast-drive`，只读取实际存在的 artifacts；若存在 `proposal.md`、`specs/*.md`，再按该 schema 的要求补充读取和审查。
+
+若当前上下文无法明确 change 或文档路径：
+
+- 先用提问工具让用户确认 change 名称或文档范围
+- 仍无法确认时，再执行 `openspec status --change "{name}" --json` 和 `openspec instructions apply --change "{name}" --json` 辅助定位
+
+若已明确 change，但尚未确认 `schemaName`，先读取 change 元数据或执行 `openspec status --change "{name}" --json` 确认。
+
+若缺少验证结果或手动修补记录，明确说明本次无法可靠判断部分差异的来源，仅能基于实际产物与文档现状审查。
+
+## 2. 分析
+
+按以下优先级检查：
+
+| 优先级 | 维度               | 检查点                                                                                                                                                                                                                                              |
+| ------ | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| P0     | 实际变更与验证结论 | 当前实际产物的真实状态是什么；apply 后是否有手动改动或验证后修补；验证是否证明这些变更有效；若缺少验证结果，标记相关结论为“未验证”；检查是否存在回归、未覆盖场景或被掩盖的问题                                                                      |
+| P1     | `design.md` 一致性 | 实际变更是否符合 `Requirements`、`Goals / Non-Goals`、`Execution Guardrails`、`Decisions`、`Execution Plan` 和 `Verification Plan`；`Open Questions` 是否已明确区分 blocking / non-blocking 或写出 `None`；是否违反被明确否决的方案、用户偏好或约束 |
+| P2     | `tasks.md` 真实性  | 已完成任务是否真的完成并完成必要验证；未完成任务是否仍然必要；apply 或手动修补是否引入了需要补充的新任务、验证任务或文档/沟通任务                                                                                                                   |
+| P3     | 文档回写完整性     | 已落地的实际变更、验证后新增修补、边界处理、异常路径、验证结论、实际触达产物是否已同步回 `design.md` 和 `tasks.md`；若影响行为、流程、接口、内容、数据、配置、责任边界或用户可见结果，再检查必要的文档/沟通材料是否同步                             |
+| P4     | 质量与可维护性     | 实际产物的结构、清晰度、一致性、可维护性、风险处理、移交质量、验证质量、与现有模式的一致性是否存在明显问题或可优化点                                                                                                                                |
+| P5     | Schema 兼容性      | 对实际存在的 artifacts 检查是否符合其 schema；若不是 `fast-drive`，仅按实际 artifacts 检查，不凭空要求 `fast-drive` 专属结构；最终 artifacts 是否仍保留模板注释、空表格行或占位任务文本                                                             |
+
+分析时区分四类差异：
+
+- `design.md` 要求已明确，但实际变更未完成或完成不充分 → 需补充实际工作或验证
+- 实际变更因验证暴露问题、手动修补或合理落地细化而新增/变更 → 需回写 `design.md` 和/或 `tasks.md`
+- 实际变更与 `design.md` 不一致，且无法判断应以哪边为准 → 列入待确认清单
+- `tasks.md` 状态与实际完成情况或验证结果不一致 → 修正任务状态或补充任务
+
+不要把以下情况直接视为合理修补：
+
+- 通过跳过、弱化或绕过验证来声称变更完成
+- 为了贴合当前实际产物而降低已确认的 requirement、acceptance criteria 或 guardrail
+- 未经过讨论和验证就扩大功能、流程、内容或责任范围
+- 违反 `Execution Guardrails`、被拒绝方案或 `Open Questions` 中尚未解决的 blocker
+
+重点识别：
+
+- `design.md` 要求但未落地的结果、流程、内容、场景、异常处理、文档/沟通更新或验证步骤
+- 实际变更偏离 `Goals / Non-Goals`、`Execution Guardrails`、`Decisions` 或 `Execution Plan` 的地方
+- apply 完成后新增的修补、边界处理、接口调整、行为变化、流程变化或内容变化未同步到 `design.md`
+- `Affected Areas` 与实际改动范围不一致，导致新会话无法复盘真实影响面
+- `Verification Plan` 中要求的验证、质量检查、审阅、批准、沟通检查或 manual checks 未执行或未记录
+- `tasks.md` 标记完成，但实际产物、验证、文档或沟通未闭环
+- `design.md` 或 `tasks.md` 仍保留 `<!-- ... -->` 模板注释、空表格行、`Replace with...`、`TBD`、`TODO` 等未解决占位内容
+- 必要的文档/沟通材料未同步影响行为、流程、接口、内容、数据、配置、责任边界或用户可见结果的变更
+- 实际产物存在明显的重复、复杂度过高、表达不清、责任不明、风险处理薄弱、验证质量不足等问题
+- `fast-drive` change 中仍错误依赖 `proposal.md`、`specs/*.md`、`Capabilities` 或 `Modified Capabilities` 的内容
+
+输出审查结果：
+
+1. **问题总览表**：问题类型 × 涉及文件数
+2. **实际变更与修补清单**：本次已落地的主要变更、后续修补和验证结论；若缺少验证结果，对未验证部分单独标记
+3. **Design 偏离清单**：实际变更未完成、完成不充分或偏离 `design.md` 的内容
+4. **需回写文档清单**：实际产物和验证中已确认、但 `design.md`、`tasks.md` 或相关文档/沟通材料未体现的变更、修补或约束变化
+5. **方向待确认清单**：实际变更与 `design.md` 不一致，且无法判断应以哪边为准的事项
+6. **任务状态问题清单**：未真正完成、状态错误或需补充的新任务
+7. **验证问题清单**：缺失覆盖、掩盖错误、验证不足或修补后未回归验证的问题
+8. **质量/优化清单**：可优化的实际产物问题和建议
+9. **Schema 差异清单**：实际 schema 与默认 `fast-drive` 不同时，列出因此跳过或改按实际 artifacts 审查的内容
+10. **逐项分析**：每个问题说明位置、问题、影响、建议和建议修复方向
+
+若所有清单均为空，输出“审查通过，未发现问题”，跳至步骤 5。
+
+## 3. 计划（用户确认）
+
+先针对“方向待确认清单”用提问工具逐项向用户确认。
+
+再整理完整修复方案，按类别列出：
+
+- 实际工作或验证补充：补完成、补异常处理、补回归验证、修复被弱化或绕过的验证
+- Design 回写：同步 `design.md` 中遗漏或过时的 requirements、guardrails、affected areas、decisions、execution plan、verification plan、risks 或 open questions
+- 任务状态修正：修正已完成/未完成状态，补充 apply 后新增但已完成的修补任务或验证任务
+- 文档/沟通同步：同步行为、流程、接口、内容、数据、配置、责任边界或用户可见结果变化
+- 质量优化：在不改变目标结果的前提下优化结构、表达、一致性、可维护性或移交质量
+- Schema 兼容处理：若实际 schema 不是 `fast-drive`，按实际存在的 artifacts 说明额外文档同步项
+
+对每个拟修改的文件说明：
+
+- 修改内容
+- 修改原因
+- 预期影响
+- 验证方式
+- 若存在分支方案，分别说明适用前提
+
+用提问工具展示完整修复方案，获得用户确认后执行。
+
+## 4. 执行
+
+逐项执行已确认的实际产物、验证和文档修复。
+
+若涉及删除或重写：
+
+- 先创建备份文件 `{file}.bak.{timestamp}`
+- 再执行修改
+
+若修改了实际产物或验证材料：
+
+- 同步更新相关变更文档；若影响行为、流程、接口、内容、数据、配置、责任边界或用户可见结果，再同步必要的文档/沟通材料
+- 运行或执行相关验证；若修补影响范围较大，再补充执行受影响的回归验证
+
+若修改了文档：
+
+- 在 `fast-drive` workflow 下，确认 `design.md` 仍是 source of truth，`tasks.md` 仍从 `design.md` 派生
+- 确认 `design.md` 的 requirements、guardrails、affected areas、decisions、execution plan、verification plan、risks 和 open questions 与实际变更一致
+- 确认 `tasks.md` 每个完成任务都有对应实际产物和必要验证，新增修补已补充任务或记录在合适任务中
+- 禁止将本次 change 内容同步到 `openspec/specs/`，该操作属于 archive 阶段
+- 在 `fast-drive` workflow 下不创建 `proposal.md` 或 `specs/*.md`；若实际 schema 不是 `fast-drive`，则按实际 schema 的 required artifacts 创建或更新本次 change 目录下的 artifacts
+
+执行后重新读取所有被修改的实际产物、验证材料和文档，并复核：
+
+- “Design 偏离清单” 是否已清空或已标注保留原因
+- “需回写文档清单” 是否已清空
+- “方向待确认清单” 是否已清空或已记录用户决策
+- “任务状态问题清单” 和 “验证问题清单” 是否已清空或已标注残留原因
+- “质量/优化清单” 中哪些已处理，哪些有意延期
+- 必要的文档/沟通材料是否已按影响范围同步
+- 所有模板注释、空表格行和占位文本是否已清空或替换为有效内容
+
+## 5. 收尾
+
+列出所有修改的文件、备份文件、验证命令或检查结果、文档同步摘要和剩余风险。
+
+若本次因缺少验证结果、修补记录或上下文而降级执行，或有问题因信息不足暂未处理，单独说明。

docs/prompts/prompt-proposal-review.md

@@ -0,0 +1,139 @@
+审查本次 OpenSpec 变更文档是否与前序讨论、当前实际状态和实际 OpenSpec workflow 一致，重点检查 `fast-drive` workflow 下的 `design.md` 是否足以在上下文压缩或新会话中指导后续 `apply`，并识别遗漏、冲突和不合理假设，给出可执行的补充建议，按以下流程执行。
+
+## 约束
+
+- 仅修改本次变更文档，不修改实际产物
+- 默认按 `fast-drive` workflow 审查；识别 change 后先确认 `schemaName`；若实际 schema 不同，说明差异，仅对实际存在的 artifacts 做审查
+- 在 `fast-drive` workflow 下，核心 artifacts 是 `design.md` 和 `tasks.md`；不要要求存在 `proposal.md` 或 `specs/*.md`
+- 在 `fast-drive` workflow 下，`design.md` 是 scope、requirements、decisions、guardrails、execution direction 和 verification expectations 的 source of truth，`tasks.md` 必须从 `design.md` 派生
+- 优先使用当前会话中的讨论、explore/propose 阶段结论和已生成的变更文档；仅在无法明确 change、`schemaName` 或文档范围时，再用提问工具或 OpenSpec 命令补充定位
+- 每批文档修改建议执行前用提问工具获得用户确认
+- 删除/重写前用提问工具获得用户确认，并先备份原文件为 `{file}.bak.{timestamp}`
+
+## 1. 收集
+
+读取约束：
+
+- 直接使用 Read 工具并行读取文件，禁止使用 subagent/Task 工具做文件读取和内容转发
+- 不原样输出文件内容，仅在步骤 2 输出审查结论
+
+分步收集：
+
+a) 先并行读取核心入口和配置，确定范围：
+
+- 本次 change 的 `design.md`
+- 本次 change 的 `tasks.md`
+- workflow context/configuration，例如存在时读取 `openspec/config.yaml`
+- 若可定位到 schema，读取对应 schema；`fast-drive` 下优先读取 `openspec/schemas/fast-drive/schema.yaml`
+
+b) 从 `design.md` 提取审查基准：
+
+- `Context`
+- `Discussion Notes`
+- `Requirements`
+- `Goals / Non-Goals`
+- `Execution Guardrails`
+- `Affected Areas`
+- `Decisions`
+- `Execution Plan`
+- `Verification Plan`
+- `Risks / Trade-offs`
+- `Open Questions`
+
+c) 基于 `Affected Areas`、`Execution Plan`、`Verification Plan`、讨论中提到的受影响范围，并行读取相关实际产物、参考材料、验证材料、流程说明、配置、文档或沟通材料，确认文档是否贴合当前实际状态。
+
+d) 若实际 schema 不是 `fast-drive`，只读取实际存在的 artifacts；若存在 `proposal.md`、`specs/*.md`，再按该 schema 的要求补充读取和审查。
+
+若当前上下文无法明确 change 或文档路径：
+
+- 先用提问工具让用户确认 change 名称或文档范围
+- 仍无法确认时，再执行 `openspec status --change "{name}" --json` 和 `openspec instructions apply --change "{name}" --json` 辅助定位
+
+若已明确 change，但尚未确认 `schemaName`，先读取 change 元数据或执行 `openspec status --change "{name}" --json` 确认。
+
+若缺少讨论记录，明确说明本次降级为“文档 + 当前实际状态审查”，不做讨论一致性结论。
+
+## 2. 分析
+
+按以下优先级检查：
+
+| 优先级 | 维度                 | 检查点                                                                                                                                                                                                                                                                            |
+| ------ | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| P0     | 讨论承接性           | 仅在存在讨论记录时检查：`design.md` 是否完整记录已确认的目标、非目标、用户偏好、约束、边界条件、风险、关键决策、被否决方案和待澄清事项；若无讨论记录，标记为“跳过”                                                                                                                |
+| P1     | `design.md` 自包含性 | `design.md` 是否足以让看不到前序对话的执行者继续工作；是否包含完整 required sections；`Open Questions` 是否明确区分 blocking / non-blocking 或写出 `None`；是否存在依赖未记录聊天上下文的隐含要求                                                                                 |
+| P2     | 当前状态真实性       | `design.md` 对当前实际产物、流程、接口、内容、数据、配置、依赖、责任边界、参考材料和验证入口的描述是否准确；是否把“计划变更”误写成“当前现状”；`Affected Areas` 是否遗漏真实受影响区域                                                                                             |
+| P3     | `tasks.md` 派生性    | `tasks.md` 是否从 `design.md` 派生；是否覆盖 requirements、guardrails、decisions、execution plan 和 verification plan；是否依赖 `proposal.md` 或 `specs/*.md` 中未写入 `design.md` 的内容                                                                                         |
+| P4     | OpenSpec 合规性      | 对实际存在的 artifacts 检查是否遵循对应 schema 和 OpenSpec 术语；`tasks.md` 是否一行一个 `- [ ]` checkbox 任务、按 `##` numbered headings 分组、无无关的仓库/版本控制/发布操作任务；`design.md` 是否避免 task checkbox；最终 artifacts 是否仍保留模板注释、空表格行或占位任务文本 |
+
+分析时区分两类情况：
+
+- 文档对当前实际状态的描述错误
+- 文档描述的是预期变更，本来就应当与当前状态不同
+
+重点识别：
+
+- 讨论中已确定但 `design.md` 未记录的内容
+- `design.md` 中缺失或含糊的 requirements、acceptance criteria、guardrails、decisions、verification expectations
+- `Open Questions` 未明确区分 blocking / non-blocking、与 `tasks.md` 冲突，或包含 apply 前必须解决的 blocker
+- `tasks.md` 未覆盖 `design.md` 的要求、约束、执行计划、验证计划或文档/沟通更新要求
+- `tasks.md` 标记了无法验证、跨行、过大、顺序错误或包含无关仓库/版本控制/发布操作的任务
+- 文档仍保留 `<!-- ... -->` 模板注释、空表格行、`Replace with...`、`TBD`、`TODO` 等未解决占位内容
+- 文档基于错误当前状态做出的设计或任务拆分
+- 文档之间相互冲突的目标、方案、约束、任务和验证要求
+- `fast-drive` change 中仍错误依赖 `proposal.md`、`specs/*.md`、`Capabilities` 或 `Modified Capabilities` 的内容
+
+输出审查结果：
+
+1. **问题总览表**：问题类型 × 涉及文档数
+2. **讨论遗漏清单**：讨论已确定但 `design.md` 未体现的内容；若缺少讨论记录，标记为“未审查”
+3. **Design 自包含性问题清单**：缺失、含糊或无法指导新会话 apply 的内容
+4. **当前状态问题清单**：与当前实际状态不符的描述、假设或影响分析
+5. **Tasks 派生与覆盖问题清单**：`tasks.md` 未从 `design.md` 正确派生或覆盖不足的内容
+6. **文档冲突清单**：`design.md`、`tasks.md` 和实际存在的其他 artifacts 之间的不一致
+7. **OpenSpec 规范问题清单**：格式、术语、结构问题
+8. **待澄清清单**：仅靠讨论和当前状态仍无法判断的事项
+9. **逐项分析**：每个问题说明位置、问题、影响、建议
+10. **补充建议方案**：按文件列出建议补充/修正的内容、原因和可选方案
+
+若所有清单均为空，输出“审查通过，未发现问题”，跳至步骤 5。
+
+## 3. 计划（用户确认）
+
+先针对“待澄清清单”用提问工具逐项向用户确认。
+
+再整理完整修复方案，按文件列出：
+
+- 建议修改的文件
+- 需要补充或修正的内容
+- 修改原因
+- 若存在分支方案，分别说明适用前提
+
+用提问工具展示完整修复方案，获得用户确认后执行。
+
+## 4. 执行
+
+逐项修改已确认的变更文档，不修改实际产物。
+
+在 `fast-drive` workflow 下，通常只修改本次 change 的 `design.md` 和 `tasks.md`；若实际 schema 存在其他 artifacts，仅在确有必要且用户确认后修改实际存在的 artifacts。
+
+若涉及删除或重写：
+
+- 先创建备份文件 `{file}.bak.{timestamp}`
+- 再执行修改
+
+执行后重新读取所有被修改的文档，并复核：
+
+- “讨论遗漏清单” 是否已清空或已标注保留原因
+- “Design 自包含性问题清单” 是否已清空
+- “当前状态问题清单” 是否已清空或已标注为预期变更
+- “Tasks 派生与覆盖问题清单” 是否已清空
+- “文档冲突清单” 是否已清空
+- “OpenSpec 规范问题清单” 是否已清空
+- “待澄清清单” 是否已清空或已记录用户决策
+- 所有模板注释、空表格行和占位文本是否已清空或替换为有效内容
+
+## 5. 收尾
+
+列出所有修改的文件、备份文件和变更摘要。
+
+若本次因缺少讨论记录而降级执行，或有问题因信息不足暂未处理，单独说明。

docs/prompts/prompt-smart-merge.md

@@ -0,0 +1,595 @@
+将所有 `dev*` 分支按计划合并到目标分支（默认 `main`），按准备→分析→计划→执行→清理执行；先探测当前仓库的规则、模块边界、验证命令和提交风格，再基于探测结果执行，避免写死仓库结构。
+
+## 约束
+
+- 全程仅使用 `git merge` 完成分支集成，禁止 `rebase`
+- `git add` 仅允许明确文件路径，禁止 `git add .`、`git add -A`
+- 不直接使用默认 `git pull`；同步目标分支时仅允许显式策略：`git fetch` + `git merge`，或 `git pull --no-rebase`
+- `git reset --hard` 仅允许回到已记录的安全锚点 tag，且执行前必须再次确认
+- `git stash push`、`git stash apply`、`git stash drop`、`git revert`、`git branch -d`、`git push {remote} --delete {branch}` 执行前都必须再次确认
+- 禁止自动推送代码；远端分支删除仅在步骤 5 获得确认后执行
+- 冲突文件禁止 AI 自主决定写入内容
+- 用户选择 `--ours`、`--theirs`、保留删除的一侧、保留重命名的一侧等机械方案后，AI 可执行对应写入
+- 凡涉及“双保留”“重组逻辑”“补写缺失代码”等内容生成，必须逐文件展示最终结果并再次获得确认后写入
+- 步骤 3 的“确认执行”仅授权按计划执行正常 merge，不授权自动执行 `stash`、`reset --hard`、`revert`、`drop`、删除分支、远端删除、冲突内容重写
+- 合并提交与语义审查修复提交必须分离；语义审查修复允许拆成多条独立提交
+- 若仓库文档定义了命令、包管理器、提交格式、目录规范，优先遵守文档；若未定义，再根据清单文件、脚本和近期提交历史推断
+- 不把当前仓库的路径结构、技术栈、构建命令写死到流程里；一切按探测结果执行
+- 信息展示按“概览 → 详情 → 原始数据”分层输出，避免一次性输出全部 diff
+
+## 记录项
+
+执行中持续维护以下记录，后续所有决策和总结都基于这些记录：
+
+| 记录项                              | 内容                                                                                    |
+| ----------------------------------- | --------------------------------------------------------------------------------------- |
+| `session_timestamp`                 | 本次流程唯一时间戳                                                                      |
+| `target`                            | 目标分支名                                                                              |
+| `target_upstream`                   | 目标分支上游，如 `{remote}/{target}`；无则记为空                                        |
+| `target_remote`                     | 从 `target_upstream` 解析出的远端名；无上游则优先使用默认远端，否则为空                 |
+| `repo_rules`                        | 从 README、CONTRIBUTING、开发文档、脚本、清单文件中识别出的规则                         |
+| `commit_style`                      | 仓库现有提交信息风格和默认合并/修复提交模板                                             |
+| `module_map`                        | 按当前仓库结构推断出的模块边界、公共目录、配置目录、基础设施目录                        |
+| `validation_commands`               | 按模块或作用域归纳出的 lint/build/test 命令                                             |
+| `auto_stashes[]`                    | 本流程创建的 stash 列表，记录唯一 message、创建时 ref、创建顺序、后续是否恢复/保留      |
+| `created_local_tracking_branches[]` | 为远端独有 `dev*` 分支创建的本地跟踪分支                                                |
+| `global_tag`                        | 全局安全锚点                                                                            |
+| `branch_tags[]`                     | 每个待合并分支对应的分支级安全锚点                                                      |
+| `analysis[]`                        | 每个分支的分析快照：HEAD hash、提交数、变更文件、依赖、初始冲突预测、风险、语义审查模式 |
+| `results[]`                         | 每个分支的最终状态：已合并、已跳过、已回退、失败原因、修复提交列表、验证结果            |
+
+## 安全锚点
+
+| 锚点                                | 创建时机                     | 用途                                                     |
+| ----------------------------------- | ---------------------------- | -------------------------------------------------------- |
+| `pre-merge-backup-{timestamp}`      | 步骤 1 完成目标分支准备后    | 全局回退点，恢复到本轮合并开始前的目标分支状态           |
+| `merge-before-{branch}-{timestamp}` | 步骤 4 每个分支正式 merge 前 | 分支级回退点，回退当前分支的合并提交和其后的语义修复提交 |
+
+除非用户明确要求“全部回退”或“放弃当前分支并回到分支级锚点”，否则不主动使用 `git reset --hard`。
+
+## 1. 准备
+
+### 1.1 仓库规则探测
+
+并行收集当前仓库的规则来源：
+
+- 根目录文档：`README*`、`CONTRIBUTING*`、`DEVELOPMENT*`、`docs/**` 中与开发、构建、测试、提交流程有关的文档
+- 常见任务入口：`Makefile`、`justfile`、`Taskfile.yml`、`package.json`、工作区配置、CI 文件、脚本目录
+- 常见清单/锁文件：`package-lock.json`、`pnpm-lock.yaml`、`yarn.lock`、`bun.lock*`、`go.mod`、`Cargo.toml`、`pyproject.toml`、`pom.xml`、`build.gradle*` 等
+- 近期提交：`git log --oneline -20`
+
+探测目标：
+
+| 项目              | 识别方式                                                      | 记录结果                     |
+| ----------------- | ------------------------------------------------------------- | ---------------------------- |
+| 包管理器/任务入口 | 文档、锁文件、任务文件、脚本                                  | 记录允许的执行方式和优先级   |
+| 模块边界          | 顶层目录、工作区配置、语言清单文件、子项目 README             | 记录 `module_map`            |
+| 公共/基础设施目录 | shared/common/lib/core/config/scripts/ci 等目录和根级配置文件 | 记录到 `module_map`          |
+| 验证命令          | 文档中的 lint/build/test 命令，或脚本中的标准任务             | 记录到 `validation_commands` |
+| 提交风格          | 文档约束优先，否则看近期 `git log`                            | 记录 `commit_style`          |
+
+识别规则：
+
+- 文档和脚本冲突时，以文档为准
+- 文档缺失时，以仓库当前可见的任务入口和近期提交习惯为准
+- 无法确定时，先在步骤 3 的计划表中展示“待确认规则”，由用户确认
+
+### 1.2 初始化现场
+
+- 执行 `git status --short --branch`，记录当前分支和工作区状态
+- 执行 `git remote -v`，记录可用远端
+- 用提问工具确认目标分支：`main` / `master` / `develop` / 用户自定义
+
+### 1.3 处理非干净工作区
+
+- 若 `git status --porcelain` 非空，先展示变更文件概览，再用提问工具让用户选择：
+  - `stash 后继续`
+  - `终止`
+- 用户选择 `stash 后继续` 后，执行 `git stash push --include-untracked -m smart-merge-{timestamp}-precheck-{n}`
+- 记录 stash 唯一 message 和创建时 ref 到 `auto_stashes[]`
+
+### 1.4 切换并校验目标分支
+
+- 执行 `git checkout {target}`
+- 若失败，使用提问工具让用户选择：
+  - `重新指定目标分支`
+  - `终止`
+
+### 1.5 解析上游并同步远端引用
+
+- 执行 `git for-each-ref --format='%(upstream:short)' refs/heads/{target}` 获取 `target_upstream`
+- 若存在 `target_upstream`：
+  - 解析 `target_remote`
+  - 执行 `git fetch {target_remote} --prune`
+  - 执行 `git rev-list --left-right --count {target}...{target_upstream}` 计算 ahead/behind
+- 若不存在 `target_upstream`：
+  - 若仓库存在默认远端，记为 `target_remote`
+  - 否则 `target_remote` 置空
+
+目标分支同步决策：
+
+| 状态             | 处理                                                                                                              |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------- |
+| 无 upstream      | 记录后继续，不自动同步                                                                                            |
+| 仅落后 upstream  | 用提问工具选择：`快进同步` / `保持当前本地 HEAD` / `终止`；若选同步，执行 `git merge --ff-only {target_upstream}` |
+| 仅领先 upstream  | 记录后继续，不自动 push                                                                                           |
+| 与 upstream 分叉 | 用提问工具选择：`保持当前本地 HEAD` / `终止`；不自动把 upstream merge 进 target                                   |
+
+### 1.6 收集候选分支
+
+- 本地分支：`git branch --list 'dev*'`
+- 若 `target_remote` 非空，远端分支：`git branch -r --list '{target_remote}/dev*'`
+- 过滤掉 `HEAD ->` 这类符号引用
+- 计算“远端存在、本地不存在”的分支列表
+
+对远端独有分支，不直接 `checkout`，改为先展示清单，再用提问工具选择：
+
+- `全部创建本地跟踪分支`
+- `选择部分创建`
+- `仅使用已有本地分支`
+- `终止`
+
+创建本地跟踪分支使用：`git branch --track {local_branch} {remote}/{remote_branch}`
+
+若本地已存在同名分支，使用提问工具逐项选择：
+
+- `使用现有本地分支`
+- `改名创建跟踪分支`
+- `跳过该远端分支`
+
+所有自动创建的本地跟踪分支都记录到 `created_local_tracking_branches[]`。
+
+### 1.7 无候选分支时直接结束
+
+- 若最终没有任何 `dev*` 分支，输出概览：目标分支、工作区状态、探测到的仓库规则、是否创建过 stash、是否创建过本地跟踪分支
+- 若本流程已创建 stash，进入步骤 5 的“工作区恢复”
+- 否则直接结束
+
+### 1.8 创建全局安全锚点
+
+- 执行 `git tag pre-merge-backup-{timestamp}`
+- 记录为 `global_tag`
+
+## 2. 分析
+
+### 2.1 信息收集（并行）
+
+对每个候选分支并行收集以下信息：
+
+| 维度     | 命令/方式                                                          | 结果                                   |
+| -------- | ------------------------------------------------------------------ | -------------------------------------- |
+| 基础     | `git rev-parse {branch}`                                           | 记录分支 HEAD hash                     |
+| 合并状态 | `git merge-base --is-ancestor {branch} {target}`                   | 判断该分支是否已完全被目标分支包含     |
+| 提交范围 | `git log --oneline {target}..{branch}`                             | 记录独有提交数和提交消息，推断分支意图 |
+| 变更范围 | `git diff --name-status {target}...{branch}`                       | 记录文件列表、状态、变更集中区域       |
+| 行数统计 | `git diff --stat {target}...{branch}`                              | 估算改动体量                           |
+| 模块归属 | 按 `module_map` 归类；若未命中则按顶层目录或最近的语言清单文件归类 | 识别受影响模块                         |
+
+模块归类优先级：
+
+1. 仓库文档明确声明的子项目、包、服务、应用、库
+2. 工作区配置或语言清单文件定义的模块边界
+3. 顶层目录边界
+4. 根级共享文件、配置文件、脚本、CI 文件，统一归为 `shared/config/infra`
+
+常见的 `shared/config/infra` 候选包括但不限于：
+
+- 根目录配置文件、锁文件、工作区文件
+- 构建脚本、部署脚本、CI 配置、容器配置、基础设施配置
+- 公共库目录、共享类型目录、通用组件目录、公共工具目录
+
+### 2.2 依赖判定
+
+依赖同时从 ancestry 和文件重叠两个维度判断：
+
+| 维度          | 方法                                                  | 判定规则                              |
+| ------------- | ----------------------------------------------------- | ------------------------------------- |
+| ancestry 依赖 | `git merge-base --is-ancestor {a} {b}`                | 若 `a` 是 `b` 的祖先，记为 `b 依赖 a` |
+| 文件重叠      | 比较各分支 `git diff --name-only {target}...{branch}` | 同一文件被多个分支修改，记为重叠      |
+| 公共文件依赖  | 关注 `shared/config/infra` 范围和公共抽象             | 即使文件数少，也记为高优先级依赖      |
+
+为每个分支输出：
+
+- `depends_on[]`：它依赖哪些分支
+- `blocks[]`：哪些分支依赖它
+- `shared_files[]`：与其他分支重叠的文件
+- `common_files[]`：被识别为公共/基础设施的文件
+
+### 2.3 初始冲突预测（串行）
+
+仅对“未合并且有实际差异”的分支串行执行：
+
+1. 执行 `git merge --no-commit --no-ff {branch}`
+2. 若工作区进入 merge 状态：
+   - 执行 `git diff --name-only --diff-filter=U` 记录冲突文件
+   - 若存在 `MERGE_HEAD`，执行 `git merge --abort`
+3. 若命令输出为 `Already up to date`、无 `MERGE_HEAD`、无冲突文件，记为“已包含或无差异”，不执行 `git merge --abort`
+4. 若 `git merge --abort` 失败：
+   - 报告错误和当前状态
+   - 用提问工具让用户选择：
+     - `回到全局锚点后继续分析`：执行 `git reset --hard {global_tag}`
+     - `终止`
+   - `reset --hard` 失败则终止并提示用户手动处理
+
+### 2.4 风险分级与排序
+
+风险评级：
+
+- 低：无预测冲突、无依赖、单一模块、小体量改动
+- 中：存在依赖，或存在预测冲突，或跨两个以上模块，或触及公共文件
+- 高：预测冲突文件 `>= 3`，或冲突占改动文件比例 `>= 30%`，或存在 ancestry 依赖且触及公共文件 / 根级配置 / 基础设施文件
+
+初始排序规则：
+
+1. 已合并 / 无差异（默认跳过，仅展示）
+2. 被其他分支依赖的基础分支
+3. 仅改公共/基础设施文件的分支
+4. 独立、低风险分支
+5. 存在依赖或共享文件的分支
+6. 高风险、跨模块分支
+
+### 2.5 验证命令归纳
+
+根据步骤 1 探测结果，为后续语义修复和构建验证归纳命令：
+
+| 作用域                 | 优先级                                  |
+| ---------------------- | --------------------------------------- |
+| 模块级 lint/build/test | 优先使用模块文档或模块脚本中声明的命令  |
+| 仓库级 lint/build/test | 若模块级命令缺失，使用仓库统一命令      |
+| 无现成命令             | 记录为“无法自动验证”，步骤 3 显示给用户 |
+
+归纳原则：
+
+- 优先使用仓库文档明确写出的命令
+- 其次使用标准任务入口中的现有命令
+- 再其次使用就近模块的标准脚本
+- 不自行发明新的构建或测试命令
+
+### 2.6 分析结果汇总
+
+为每个分支形成分析快照：
+
+| 字段                   | 内容                               |
+| ---------------------- | ---------------------------------- |
+| `status`               | 已合并 / 无差异 / 待合并           |
+| `head`                 | 步骤 2 记录的 HEAD hash            |
+| `modules`              | 受影响模块                         |
+| `files`                | 改动文件数                         |
+| `depends_on`           | 依赖分支                           |
+| `predicted_conflicts`  | 初始冲突文件列表                   |
+| `risk`                 | 低 / 中 / 高                       |
+| `semantic_review_mode` | 默认 `仅报告`                      |
+| `validation_scope`     | 该分支后续优先使用的验证范围和命令 |
+
+## 3. 计划（用户确认）
+
+输出合并计划表，列至少包含：
+
+| 分支 | 状态 | 模块 | 文件数 | 依赖 | 预测冲突 | 风险 | 语义审查 | 验证命令 |
+| ---- | ---- | ---- | ------ | ---- | -------- | ---- | -------- | -------- |
+
+默认规则：
+
+- `已合并`、`无差异` 分支仅展示，不进入执行队列
+- `待合并` 分支按步骤 2.4 的排序进入执行队列
+- `语义审查` 默认值为 `仅报告`
+- 若某分支缺少可自动执行的验证命令，在计划表中明确标记
+
+同时展示仓库级探测结果摘要：
+
+- 识别出的模块边界
+- 公共/基础设施范围
+- 识别出的验证命令
+- 提交风格摘要
+- 无法确定、需要用户补充的规则
+
+用提问工具让用户选择：
+
+- `确认执行`
+- `调整顺序`
+- `排除分支`
+- `调整语义审查模式`
+- `补充或修正规则`
+- `重新分析全部分支`
+- `终止`
+
+语义审查模式仅允许三种：
+
+- `关闭`
+- `仅报告`
+- `报告并修复`
+
+若用户选择 `调整顺序`、`排除分支`、`调整语义审查模式`、`补充或修正规则`、`重新分析全部分支`，则更新计划表后再次确认，直到用户选择 `确认执行` 或 `终止`。
+
+最终确认后，记录最终执行队列。并明确提示：
+
+- 正常 merge 已获授权
+- 冲突内容重写、`stash`、`revert`、`reset --hard`、删除分支、远端删除仍需单独确认
+
+## 4. 执行（顺序执行，冲突/异常时中断）
+
+对执行队列中的分支依次处理。若队列为空，直接进入步骤 5。
+
+### 4.1 单分支合并前检查
+
+每个分支开始前都执行以下检查：
+
+1. `git status --short --branch`，确认当前仍在 `{target}`
+2. 若不在 `{target}`，执行 `git checkout {target}`；失败则中断并询问
+3. 若工作区非干净，展示异常文件，并用提问工具让用户选择：
+   - `stash 后继续`
+   - `终止`
+4. 若用户选择 `stash 后继续`，执行 `git stash push --include-untracked -m smart-merge-{timestamp}-runtime-{n}`，记录到 `auto_stashes[]`
+5. 检查分支是否仍存在；不存在则记录为 `已跳过：分支不存在`
+6. 执行 `git rev-parse {branch}`，对比步骤 2 记录的 `head`
+7. 若 HEAD 已变化，先对该分支重新执行步骤 2 的单分支分析，再更新计划快照
+
+### 4.2 基于当前 HEAD 的动态复核
+
+步骤 2 的分析基于初始目标分支；每次实际 merge 前都必须基于“当前最新 HEAD”重新复核当前分支：
+
+1. 执行 `git diff --name-status HEAD...{branch}`，获取当前变更文件列表
+2. 串行执行 `git merge --no-commit --no-ff {branch}` 做实时 dry-run
+3. 若进入 merge 状态，收集 `git diff --name-only --diff-filter=U` 冲突文件后执行 `git merge --abort`
+4. 若无 `MERGE_HEAD`，按实际结果记为“无冲突”或“已包含 / 无差异”
+5. 将实时结果与步骤 3 的计划快照对比
+
+视为“计划漂移”的情况：
+
+- 冲突文件集合发生变化
+- 改动文件数变化明显（以 `20%` 为阈值）
+- 新出现公共文件 / 根级配置 / 基础设施文件
+- 原本 `无冲突` 变成 `有冲突`
+- 原本模块级验证命令不再覆盖当前改动范围
+
+若发生计划漂移，用提问工具让用户选择：
+
+- `按更新后的当前结果继续`
+- `重新生成剩余分支计划`：对“当前分支 + 尚未处理的剩余分支”重新执行步骤 2，再回到步骤 3
+- `跳过当前分支`
+- `终止`
+
+### 4.3 生成提交模板并创建分支级锚点
+
+先根据 `commit_style` 生成本轮使用的提交模板：
+
+- 若仓库文档明确约束了提交格式，严格遵守
+- 若文档未约束，但近期提交风格稳定，沿用仓库现有风格
+- 若无法识别，合并提交使用 `chore: merge {branch} into {target}`，语义修复提交使用 `refactor: address post-merge issues in {branch}`
+
+然后：
+
+- 执行 `git tag merge-before-{branch}-{timestamp}`
+- 记录到 `branch_tags[]`
+
+### 4.4 正式合并
+
+- 执行正式合并：`git merge --no-ff -m "{merge_commit_message}" {branch}`
+
+正式合并结果分三类：
+
+- 无冲突：进入步骤 4.6
+- 有冲突：进入步骤 4.5
+- 非冲突错误：展示错误信息，用提问工具选择：`跳过当前分支` / `终止`
+
+### 4.5 冲突处理（中断点）
+
+先执行 `git diff --name-only --diff-filter=U` 获取冲突文件清单，再按文件生成冲突决策面板：
+
+| #   | 文件 | 冲突类型 | HEAD 改动摘要 | 分支改动摘要 | 可批量机械处理 | 推荐方案 |
+| --- | ---- | -------- | ------------- | ------------ | -------------- | -------- |
+
+推荐方案规则：
+
+- 仅当解决方案明确等价于 `--ours`、`--theirs`、保留删除的一侧、保留重命名的一侧时，才允许给出“可批量机械处理”的推荐
+- 只要需要合并两边逻辑、补全缺失分支、重排代码顺序、解决同一函数 / 类 / 配置段双改，就标记为 `需逐文件确认`
+- `需逐文件确认` 的文件不能被“全部按推荐方案”一键处理
+
+用提问工具让用户选择：
+
+- `处理全部机械型冲突`
+- `审查部分文件`
+- `放弃当前合并`
+
+若用户选择 `审查部分文件`，先让用户输入文件编号，再对这些文件逐个展示：
+
+- 上下文 diff
+- 原始冲突块 `<<<<<<<` / `=======` / `>>>>>>>`
+- 当前建议与风险说明
+
+逐文件可选方案：
+
+- `保留目标 (--ours)`
+- `保留分支 (--theirs)`
+- `AI 起草双保留结果`
+- `用户手动编辑`
+
+执行规则：
+
+- `--ours` / `--theirs`：执行 `git checkout --ours/--theirs {file}`
+- `AI 起草双保留结果`：
+  - 先生成完整最终结果或统一 diff
+  - 说明具体合并逻辑
+  - 再次用提问工具确认后写入文件
+- `用户手动编辑`：告知文件路径，等待用户回复“完成”后再执行 `git add {file}`
+- 所有冲突文件都必须逐文件 `git add {file}`
+- 执行 `git diff --name-only --diff-filter=U`，确认已无未解决冲突
+- 再执行 `git commit --no-edit`
+
+若用户选择 `放弃当前合并`：
+
+- 用提问工具确认是否执行 `git merge --abort`
+- 若 `abort` 成功，记录当前分支为 `已跳过：用户放弃合并`
+- 若 `abort` 失败，再用提问工具确认是否执行 `git reset --hard merge-before-{branch}-{timestamp}` 回到分支级锚点
+
+### 4.6 语义审查
+
+语义审查基于 `git diff merge-before-{branch}-{timestamp}..HEAD`。
+
+辅助数据源：
+
+| 数据          | 获取方式                                           | 用途                             |
+| ------------- | -------------------------------------------------- | -------------------------------- |
+| 本次合入 diff | `git diff merge-before-{branch}-{timestamp}..HEAD` | 查看本次实际引入的改动           |
+| 分支意图      | 步骤 2 的 commit 消息                              | 推断业务目的                     |
+| 主干近期趋势  | `git log --oneline {target} -20` 及相关 diff       | 识别近期重构、迁移、废弃方向     |
+| 公共文件现状  | 步骤 2 标记的 `common_files[]`                     | 判断是否重复造轮子或遗漏基础设施 |
+| 仓库规则      | `repo_rules`、`module_map`、`validation_commands`  | 判断是否偏离当前仓库约定         |
+
+审查维度：
+
+| 维度         | 检查点                                                                                                 |
+| ------------ | ------------------------------------------------------------------------------------------------------ |
+| 代码冗余     | 新增函数、组件、类型、工具、配置是否已在仓库公共位置存在等价实现                                       |
+| 过时模式     | 是否继续使用近期已迁移、废弃、替换的 API、脚本、配置项、目录模式                                       |
+| 基础设施遗漏 | 新代码是否绕过既有公共抽象、统一错误处理、统一日志、统一配置、统一数据访问、统一请求封装等既有基础设施 |
+| 风格不一致   | 命名、文件组织、测试组织、错误处理、注释风格是否偏离当前主干                                           |
+| 模块边界破坏 | 是否把本应落在公共层、共享层、基础设施层的逻辑塞进业务分支目录                                         |
+
+输出审查结果表：
+
+| #   | 类别 | 严重程度 | 文件 | 描述 | 建议修复方式 |
+| --- | ---- | -------- | ---- | ---- | ------------ |
+
+严重程度仅分两类：
+
+- `问题`：有运行时风险、明显架构偏差或维护成本高
+- `建议`：功能可用，但与主干一致性较差
+
+按计划中的 `semantic_review_mode` 处理：
+
+- `关闭`：跳过语义审查
+- `仅报告`：展示结果后直接进入步骤 4.7
+- `报告并修复`：展示结果后，用提问工具选择：`全部修复` / `选择修复` / `跳过`
+
+修复执行规则：
+
+1. 每个问题编号视为一个独立修复单元
+2. 一次只处理一个编号，避免回退时互相污染
+3. 每个修复单元只修改其必要文件，保持最小变更
+4. 修复完成后，按 `validation_commands` 和当前改动作用域执行最小充分检查：
+
+| 作用域                     | 检查策略                               |
+| -------------------------- | -------------------------------------- |
+| 仅单模块                   | 优先执行该模块的 lint 或等价静态检查   |
+| 多模块                     | 执行覆盖这些模块的仓库级检查或组合检查 |
+| 触及 `shared/config/infra` | 执行受影响范围内最严格的可用检查       |
+| 无自动检查命令             | 记录为“未自动验证”，并在结果中明确说明 |
+
+5. 若检查通过，立即提交独立修复 commit，message 遵循 `commit_style`
+6. 若检查失败，只回退当前修复单元的未提交修改：`git restore --staged --worktree --source=HEAD -- {files}`
+7. 记录该编号为 `修复失败并已回退`，继续处理下一个编号
+
+### 4.7 构建验证
+
+根据当前分支实际引入的改动范围，从 `validation_commands` 中选择最小充分的构建 / 测试 / 检查命令：
+
+| 改动范围                   | 验证策略                                     |
+| -------------------------- | -------------------------------------------- |
+| 单模块业务改动             | 优先运行该模块的 build / test / lint 组合    |
+| 多模块改动                 | 运行覆盖这些模块的聚合命令                   |
+| 触及共享层、配置、基础设施 | 优先运行仓库级验证或覆盖共享层的更高等级验证 |
+| 仓库没有可自动执行命令     | 记录为“无法自动验证”，并向用户说明           |
+
+构建成功：
+
+- 记录当前分支为 `已合并`
+- 记录冲突处理方式、语义审查结果、修复提交列表、实际执行的验证命令
+- 继续下一个分支
+
+构建失败：
+
+1. 展示失败命令和错误摘要
+2. 若当前分支存在语义修复提交，用提问工具让用户选择：
+   - `依次 revert 当前分支的语义修复提交后重试验证`
+   - `放弃当前分支并回到分支级锚点`
+   - `终止`
+3. 若用户选择 revert：
+   - 按提交时间倒序执行 `git revert --no-edit {commit}`
+   - 每 revert 一条后重试验证，直到通过或全部 revert 完成
+   - 若 revert 冲突，立即中断并询问：`回到分支级锚点` / `保留冲突现场并终止`
+4. 若无语义修复提交，或全部 revert 后验证仍失败，用提问工具让用户选择：
+   - `git reset --hard merge-before-{branch}-{timestamp}` 放弃当前分支
+   - `终止并保留当前现场`
+5. 若用户确认回到分支级锚点，记录当前分支为 `已跳过：验证失败并回退`
+
+## 5. 清理（用户确认）
+
+所有分支处理完成后，输出汇总表：
+
+| 项目       | 内容                                                                                 |
+| ---------- | ------------------------------------------------------------------------------------ |
+| 目标分支   | `{target}`                                                                           |
+| 当前 HEAD  | 当前提交 hash                                                                        |
+| 合并结果   | 成功 / 跳过 / 已合并 / 无差异 数量                                                   |
+| 冲突统计   | 冲突分支数、冲突文件数、机械处理数、逐文件确认数                                     |
+| 语义审查   | 每个分支的问题数、建议数、修复成功数、修复失败数                                     |
+| 实际验证   | 每个分支实际执行了哪些验证命令，哪些未验证                                           |
+| 已创建资源 | `global_tag`、`branch_tags[]`、`auto_stashes[]`、`created_local_tracking_branches[]` |
+| 候选删除   | 可删除的本地分支、远端分支、可删除 tag                                               |
+
+用提问工具一次性确认清理策略：
+
+- `确认清理`
+- `调整清理范围`
+- `跳过清理`
+
+清理项包括：
+
+- 删除已成功合并的本地分支：`git branch -d {branch}`
+- 删除已成功合并且用户确认的远端分支：`git push {remote} --delete {branch}`
+- 删除用户明确不再保留的安全锚点 tag
+- 删除本流程仅为分析/合并而创建、且最终不需要保留的本地跟踪分支
+
+远端分支删除规则：
+
+- 优先删除该分支自己的 upstream remote
+- 若分支无 upstream，但来自 `target_remote`，则删除 `target_remote/{branch}`
+- 删除失败只记录错误，不影响其余清理项
+
+### 工作区恢复
+
+若 `auto_stashes[]` 非空，用提问工具让用户选择：
+
+- `按顺序恢复全部 stash`
+- `查看 stash 列表后选择恢复`
+- `暂不恢复，保留 stash`
+
+恢复时按后进先出顺序处理。由于 `stash@{n}` 会随列表变化而漂移，先根据已记录的唯一 message 在 `git stash list` 中定位当前 ref，再对该 stash 执行 `git stash apply {ref}`，不直接 `pop`：
+
+1. `apply` 成功后，再询问是否 `git stash drop {ref}`
+2. 若 `apply` 冲突，展示 stash 冲突决策面板，逐文件选择：
+   - `保留 stash 内容`
+   - `保留当前内容`
+   - `AI 起草双保留结果`
+   - `用户手动编辑`
+   - `放弃恢复该 stash`
+3. 冲突解决完成后，再询问是否 `drop` 对应 stash
+
+输出最终总结：目标分支、当前 HEAD、探测到的仓库规则摘要、保留的锚点、各分支最终状态、未删除的远端分支、stash 恢复结果。
+
+## 终止处理
+
+任一步骤选择 `终止` 时，输出终止摘要：
+
+| 项目       | 内容                                                                                 |
+| ---------- | ------------------------------------------------------------------------------------ |
+| 当前步骤   | 准备 / 分析 / 计划 / 执行 / 清理                                                     |
+| 当前 HEAD  | 当前提交 hash                                                                        |
+| 已完成分支 | 成功合并的分支                                                                       |
+| 已跳过分支 | 分支及原因                                                                           |
+| 未处理分支 | 剩余执行队列                                                                         |
+| 已创建资源 | `global_tag`、`branch_tags[]`、`auto_stashes[]`、`created_local_tracking_branches[]` |
+| 已识别规则 | `repo_rules`、`module_map`、`validation_commands`                                    |
+
+若终止时存在活动 merge 状态，再用提问工具让用户选择：
+
+- `执行 git merge --abort 并结束`
+- `回到当前分支级锚点并结束`
+- `保留当前冲突现场，交给用户手动处理`
+
+若终止时不存在活动 merge 状态，不自动变更现场；仅提示用户：
+
+- 全部回退可使用 `git reset --hard {global_tag}`
+- 当前分支级回退可使用 `git reset --hard merge-before-{branch}-{timestamp}`
+- 本流程创建的 stash 和本地跟踪分支仍保留，是否恢复/删除由步骤 5 或用户后续手动决定