speckit-converge

用户输入

$ARGUMENTS

如果用户输入不为空，必须在继续前考虑用户输入。

执行前检查

检查扩展钩子（收敛前）：

• 检查项目根目录中是否存在 .specify/extensions.yml。

• 如果存在，读取该文件，并查找 hooks.before_converge 键下的条目。

• 如果 YAML 无法解析或无效，不得默默跳过：告知用户 .specify/extensions.yml 无法读取（包含解析器错误），并说明未检查任何钩子，包括其中注册的任何强制钩子（optional: false），然后正常继续。

• 过滤掉 enabled 明确为 false 的钩子。没有 enabled 字段的钩子默认视为已启用。

• 对每个剩余钩子，不要尝试解释或评估钩子的 condition 表达式：

  • 如果钩子没有 condition 字段，或其值为 null／空，则视为可执行。
  • 如果钩子定义了非空的 condition，则跳过该钩子，并将条件评估留给 HookExecutor 实现处理。

• 根据钩子命令名称构造命令调用时，将点号（.）替换为连字符（-）。例如，speckit.git.commit → /speckit-git-commit。

• 对每个可执行钩子，根据其 optional 标志输出以下内容：

  • 可选钩子（optional: true）：

    ## 扩展钩子
    
    **可选前置钩子**：{extension}
    命令：`/{command}`
    说明：{description}
    
    提示词：{prompt}
    执行方式：`/{command}`
    

  • 强制钩子（optional: false）：

    ## 扩展钩子
    
    **自动前置钩子**：{extension}
    正在执行：`/{command}`
    EXECUTE_COMMAND: {command}
    
    请等待钩子命令的结果后再继续执行目标。
    

    输出上述内容块后，必须实际调用该钩子，并等待其完成后再继续。按照在此 Agent／会话中亲自运行命令的方式运行它（调用方式可能与显示的 {command} ID 不同，例如，技能模式的 Agent 会运行 /skill:speckit-... 或 $speckit-...）。仅输出该内容块并不等于运行了钩子。

• 如果没有注册钩子，或 .specify/extensions.yml 不存在，则静默跳过。

目标

弥合功能规范、计划和任务所要求的内容与代码库当前实现之间的差距。将 spec.md、plan.md 和 tasks.md 作为意图的唯一来源（以章程作为约束），评估代码的当前状态，确定哪些需求、验收标准、计划决策和现有任务尚未满足、尚未完成或仅部分满足，并将每项剩余工作作为可追溯的新任务追加到 tasks.md 末尾，以便 /speckit-implement 完成这些工作。只有在针对当前 tasks.md 运行过 /speckit-implement，且 /speckit-tasks 已生成完整的 tasks.md 后，才能运行此命令。

这不是差异对比工具，也不会追踪变更。它会根据功能相关文档评估代码的当前状态，不涉及 git、分支比较或历史记录。

运行约束

仅追加，绝不重写：该命令唯一的写入操作是在 tasks.md 中追加一个新的 ## Phase N: Convergence 章节。绝不能：

• 以任何方式修改 spec.md 或 plan.md；
• 重写、重新编号、重新排序或删除任何现有任务（包括先前 Convergence 阶段中的任务）；
• 修改、创建或删除任何应用代码——完成追加任务是 /speckit-implement 的职责。

如果代码库已满足所有要求，该命令必须保持 tasks.md 逐字节不变（不得添加空的 Convergence 标题），并报告结果无误。

章程权威性：项目章程（.specify/memory/constitution.md）不可协商。违反 MUST 原则的代码属于严重程度最高的问题，并须生成相应的修复任务。如果章程仍是未填写的模板，则应跳过章程检查，不得因此失败。

执行步骤

1. 初始化 Convergence 上下文

从仓库根目录运行一次 .specify/scripts/bash/check-prerequisites.sh --json --require-spec --require-tasks --include-tasks，并解析 JSON，获取 FEATURE_DIR 和 AVAILABLE_DOCS。派生绝对路径：

• SPEC = FEATURE_DIR/spec.md
• PLAN = FEATURE_DIR/plan.md
• TASKS = FEATURE_DIR/tasks.md
• CONSTITUTION = .specify/memory/constitution.md（如果存在） 如果缺少 spec.md、plan.md 或 tasks.md，则停止并给出清晰、可执行的提示，指出应运行的前置命令（缺少 spec 时运行 /speckit-specify，缺少 plan 时运行 /speckit-plan，缺少 tasks 时运行 /speckit-tasks）。不要生成部分输出。 对于参数中的单引号，例如 "I'm Groot"，请使用转义语法，例如 'I'''m Groot'（或尽可能使用双引号："I'm Groot"）。

2. 加载工件（渐进式披露）

仅从每个工件中加载最低限度的必要上下文：

从 spec.md 中：

• 功能需求（FR-###）
• 成功标准（SC-###）——仅包括需要构建工作的项目；排除发布后的结果指标和业务 KPI
• 用户故事及其验收场景
• 边缘情况（如有）

从 plan.md 中：

• 架构／技术栈选择和技术决策
• 数据模型引用
• 阶段和命名的接触点（计划中注明将创建或编辑的文件／组件）
• 技术约束

从 tasks.md 中：

• 任务 ID（用于计算下一个 ID 和阶段编号）
• 描述、阶段分组和引用的文件路径

从章程中（如果不是未填写的模板）：

• 原则名称及 MUST／SHOULD 规范性陈述

3. 构建意图清单

创建内部模型（不要回显原始工件）：

• 需求清单：为每个 FR-###／SC-###／用户故事验收场景分配一个稳定键（例如 US1/AC2），并纳入施加了可构建义务的计划决策和章程原则。
• 代码范围映射：根据 plan.md 和 tasks.md 中列出的文件路径，再结合对每项需求所述概念的关键词搜索，推导出纳入评估范围的源文件和组件集合。将评估范围限制在这些内容之内——不要推断超出工件定义范围的内容。

4. 评估代码库并对发现分类

将意图清单中的所有现有任务都纳入评估，无论其复选框状态或 Convergence 阶段如何：完成声明并非证据。根据规范、计划、任务和章程核实当前行为；对于纠正性任务链，评估最终行为，而非已被取代的实现细节。检查未履行的义务，以及与既定意图相矛盾、超出意图范围或不属于意图范围的实现。

对于意图清单中的每一项，检查当前范围内的代码，仅在存在差距时生成 Finding。按差距类型对每项发现分类：

• missing：代码中完全缺少所需工作。
• partial：已有相关工作，但尚未完全满足要求 / 验收标准 / 计划决策。
• contradicts：代码的行为与既定意图或章程中的 MUST 原则冲突。
• unrequested：代码包含规范、计划或任务未要求的工作（仅供了解——converge 不会删除代码，只会追加一项任务，以供审查、说明理由或移除）。

每项 Finding 都要记录：稳定 ID、用于追溯的 source-ref、gap-type、严重程度，以及简短易懂的描述和证据（观察到问题的文件 / 区域）。

边界情况：

• 代码很少或尚无代码：将整个指定范围视为尚待完成的 missing 工作，而不是判定失败。
• 没有遗留事项：不生成任何发现，并在步骤 7 中遵循已收敛分支。

5. 指定严重程度

• CRITICAL：违反章程中的 MUST 原则，或 missing / contradicts 差距导致 P1 用户故事的基线功能受阻。
• HIGH：核心功能要求或验收标准存在 missing 或 partial 差距。
• MEDIUM：次要要求存在 partial 差距，或存在理由不明的 unrequested 增补。
• LOW：轻微的 partial 差距、润色问题或低风险的 unrequested 增补。

6. 在当前会话中展示发现摘要

追加任何内容之前，先输出一份按严重程度分类的简明摘要（暂不写入文件）：

Convergence 发现

ID	差距类型	严重程度	来源	证据	待完成工作
F1	missing	HIGH	FR-008	示例：在 path/to/module.py 中写入 tasks.md 时，未发现仅追加保护机制	添加仅追加机制

摘要指标：

• 已检查的要求 / 验收标准
• 已检查的计划决策
• 已检查的章程原则（或“已跳过 — 模板”）
• 按差距类型统计的发现（missing / partial / contradicts / unrequested）
• 按严重程度统计的发现

7. 追加收敛任务（或报告已收敛）

如果有一个或多个可执行的发现（tasks_appended 结果）：

根据追加约定，追加到 tasks.md 末尾：

1. 扫描所有现有任务 ID；令 M 为最大值。确定下一个阶段编号 N （现有阶段编号中的最大值 + 1）。

2. 写入一个新的章节标题 ## Phase N: Convergence。

3. 每个可执行的发现生成一个检查清单项，按 CRITICAL/HIGH 优先排序，并分配 零填充 ID：T{M+1:03d}, T{M+2:03d}, …：

   - [ ] T042 <imperative description> per <source-ref> (<gap-type>)
   

   <source-ref> 将任务追溯到其来源，例如：FR-003、SC-002、 US1/AC2、plan: storage decision、Constitution II。

   <gap-type> 是以下值之一：missing、partial、contradicts、unrequested。

   违反 Constitution 的任务 MUST 首先列出，并描述为 CRITICAL。

4. 绝不重复使用或重新编号现有 ID。如果之前已有 Convergence 阶段，则在其下方添加一个新的、 单独编号的阶段——不要修改旧阶段。

如果没有可执行的发现（converged 结果）：

• 不要修改 tasks.md——不要添加空的阶段标题。
• 报告：“✅ 已收敛 — 实现满足规范、计划和任务的要求。”
• 包含已检查内容的汇总计数。

8. 提供后续操作（交接）

• 对于 tasks_appended：说明追加了多少个任务以及它们属于哪个阶段，并建议 运行 /speckit-implement 来完成这些任务；同时说明后续再次运行 converge 时，剩余项目会更少或不再有剩余项目。
• 对于 converged：建议继续进行审查 / 创建 PR。此功能指定范围内无需再运行 implement。

9. 检查扩展钩子

生成结果后，检查项目根目录中是否存在 .specify/extensions.yml。

• 如果存在，读取该文件并查找 hooks.after_converge 键下的条目

• 如果 YAML 无法解析或无效，不要默默跳过：告知用户无法读取 .specify/extensions.yml（包括解析器错误），并说明未检查任何钩子，包括其中注册的任何强制钩子（optional: false），然后继续正常操作

• 排除 enabled 明确为 false 的钩子。未设置 enabled 字段的钩子默认视为已启用。

• 对于每个剩余钩子，不要尝试解读或评估钩子的 condition 表达式：

  • 如果钩子没有 condition 字段，或该字段为 null/空，则将钩子视为可执行
  • 如果钩子定义了非空的 condition，则跳过该钩子，并将条件评估留给 HookExecutor 实现

• 在列出任何钩子之前，先在当前会话中报告收敛结果（converged 或 tasks_appended），以便用户决定是否运行可选的后续命令。

• 从钩子命令名称构造命令调用时，将点号（.）替换为连字符（-）。例如，speckit.git.commit → /speckit-git-commit。

• 对于每个可执行钩子，根据其 optional 标志输出以下内容：

  • 可选钩子（optional: true）：

    ## 扩展钩子
    
    **可选钩子**：{extension}
    命令：`/{command}`
    描述：{description}
    
    提示词：{prompt}
    执行：`/{command}`
    

  • 强制钩子（optional: false）：

    ## 扩展钩子
    
    **自动钩子**：{extension}
    正在执行：`/{command}`
    EXECUTE_COMMAND: {command}
    

    输出以上内容后，MUST 实际调用该钩子，并等待其执行完毕后再继续。像在此 Agent/会话中自行运行命令那样运行它（实际调用方式可能与上面显示的字面 {command} ID 不同，例如，技能模式 Agent 会将其作为 /skill:speckit-... 或 $speckit-... 运行）。仅输出此代码块并不算运行钩子。

• 如果未注册任何钩子，或 .specify/extensions.yml 不存在，则静默跳过