spec-merger

Spec 合并器

捆绑运行时

执行下方的 CLI 命令行之前，将开头的 SSF 替换为 node "<plugin-root>/scripts/spec-superflow.mjs"；<plugin-root> 是本文件上两级目录的绝对路径。切勿直接运行 SSF，也不要调用 PATH 中的 ssf。

在最终的 executing → closing 转换之前，必须将增量规格（ADDED/MODIFIED/REMOVED/RENAMED）发布到主规格基线中。changes/<change>/ 仍是当前工作流的来源；根目录的 specs/ 仅作为已发布的基线。未同步的规格会变成谎言。 已处于 closing 的变更不得路由到 spec-merger。

执行状态防护

执行 SSF sync 或任何其他写入操作之前，运行 SSF state get <change-dir> state。 仅当持久化状态恰好为 executing 时才继续。如果状态为 closing → STOP：「Closing 是终态。不要将此变更路由到 spec-merger； 同步必须在最终的 executing → closing 转换之前完成。」对于 任何其他状态，或者无法读取状态时 → STOP 并路由到 workflow-start；不要执行副作用。

执行前检查

冲突检测

运行 SSF sync <change-dir>。如果检测到冲突（多个变更修改了同一需求），请向用户展示冲突列表，以便确定解决顺序。

同步流程

步骤 1：识别增量

变更文件夹下的每个 specs/<capability>/spec.md 都包含 ## ADDED/MODIFIED/REMOVED/RENAMED Requirements 下的增量操作。

## Purpose 是可选的顶层增量扩展。仅在创建规范主规格时使用。当它缺失或为空时，同步结果会使用并报告确定性默认 Purpose，以便旧版增量规格仍可用。增量 Purpose 不得覆盖现有主规格中的 Purpose。

步骤 2：按操作应用

ADDED：将需求追加到已发布基线的 ## Requirements 中。如果规范主规格不存在，则创建一个。

MODIFIED：根据 ### Requirement: <name> 匹配，并替换其描述和场景。如果规范基线中不存在此需求，则标记出来。

REMOVED：从已发布基线中移除匹配的需求。如果该需求不存在，则标记出来。

RENAMED：匹配旧名称，并将其标题改为新名称。如果新名称与现有需求冲突，则标记出来。

步骤 3：冲突检测

执行前，检测以下情况：

• 多个未同步的变更修改了同一需求 → 手动解决
• RENAMED 的目标与现有需求冲突 → 手动解决
• MODIFIED/REMOVED 针对不存在的需求 → 标记出来

步骤 4：执行合并

写入任何目标之前，验证每个候选主规格。仅应用有变更的候选项。已在基线中体现的操作属于幂等空操作，必须报告未执行写入。若操作目标不存在，但存在仅大小写或空白字符不同的相近匹配项，则视为错误，而非空操作。切勿删除增量规格——它们必须保留以供追溯。根基线必须包含 ## Requirements，绝不能包含 ## ADDED/MODIFIED/REMOVED/RENAMED Requirements 标题。对于无法解释且不安全的旧版纯增量基线，应拒绝处理，不得猜测。

步骤 5：报告

输出同步报告表格：Capability、ADDED/MODIFIED/REMOVED/RENAMED 数量、Status（✓/⚠）。提供汇总统计和未解决的冲突。

防护措施

• 不要删除增量规格文件（历史记录）
• 不要自动解决不同变更之间的冲突
• 不要合并未经验证的变更的规格
• 发布前验证每个候选主规格；验证失败时，不得写入任何目标
• 仅将语义等效且已应用的操作视为空操作；需求名称的近似匹配必须判为失败

同步后

1. 报告结果。如果没有冲突 → 可以归档。如果存在冲突 → 用户必须先解决冲突，再进行归档。
2. 变更文件夹（包括差异）会保留，以便追溯。
3. SSF sync 会自动将发布回执写入活动变更状态。不要手动设置 spec_merged：这个旧版标记不能作为关闭依据。关闭检查会重新计算差异和已发布基线的哈希，因此之后的任何编辑都需要再次同步。
4. 如果变更没有差异章节，则不需要发布回执。

异常处理

• 解析失败：报告文件和章节。不要尝试部分合并。
• 没有差异：如果变更没有差异章节，则报告无需合并，并正常退出。
• 用户中断：恢复时，先检查是否存在合并冲突标记，再继续。