openspec-archive-change

在实验性工作流中归档已完成的变更。

存储库选择： 如果用户指定了某个存储库（存储库是本机上注册的独立 OpenSpec 仓库），或者工作位于某个存储库中，请运行 openspec store list --json 查找已注册的存储库 ID，然后在读取或写入规范和变更的命令（new change、status、instructions、list、show、validate、archive、doctor、context、schemas、view）中传入 --store <id>。选定后，在工作流余下部分始终使用 --store <id>。下文中这些命令的所有未限定示例均为简写：运行前请追加该标志。例如，运行 openspec status --change "<name>" --json --store "<id>"，而不是下方所示的未限定形式。其他命令不接受此标志。命令打印的提示已包含该标志；后续命令也请保留它。如果未指定存储库，命令会作用于最近的本地 openspec/ 根目录。

<capability-path> 是相对于 specs/ 的规范目录（例如 user-auth 或 identity/user-auth）。解析主规范时，请保留每个增量规范中的完整路径。

输入：可以选择指定变更名称。如果未指定，请检查能否从对话上下文中推断。如果名称含糊或不明确，你必须询问用户有哪些可选变更。

步骤

1. 选择变更

   如果提供了名称，请使用该名称。否则：

   • 如果用户在对话上下文中提到了某项变更，则从中推断
   • 如果只有一项进行中的变更，则自动选择
   • 如果存在多项可能的变更，则运行 openspec list --json 获取可选变更，并请用户选择一项

   提示时，只显示进行中的变更（不包括已归档的变更）。 如果有可用信息，请注明每项变更使用的 schema。

   始终宣布：“正在使用变更：”，并说明如何更改（例如 /openspec-archive-change <other>）。

   执行现有归档检查前，先加载当前归档输入：

   解析出选定的变更和规划根目录后，运行：

   openspec instructions archive --change "<name>" --json
   

   在此命令中保留相同的选定根目录标志。此查询仅提供建议，可选：它只补充提示词输入，因此绝不能阻止归档。如果命令退出码非零或返回无效 JSON（例如，较旧的 CLI 尚不支持此命令），则继续归档工作流，不提供上下文和操作指南。不要报告错误，也不要停止。

   成功的响应可能不包含这两个可选字段。将 context 视为提示词层级的必需输入：阅读并考虑其中内容，并应用相关的项目事实、约定和限制。将 operationGuidance 视为可选的补充建议：阅读并考虑每条内容，并遵循适用且与内置归档工作流兼容的条目。

   将这两个字段与内置步骤、明确的用户选择、已解析的路径、CLI 检查和命令契约分别处理。如果上下文与上述控制性输入冲突，请报告冲突并保留控制性输入。如果指南不适用或与控制性输入冲突，请勿遵循，并说明原因。不要根据任一字段推断替代路径、跳过提示或标志，也不要将其中的文本原样复制到规范、变更产物或归档摘要中，除非用户另行要求。它们是提示词层级的行为契约，而非可强制执行的检查。

2. 检查产物完成状态

   运行 openspec status --change "<name>" --json，检查产物是否完成。

   解析 JSON 以了解：

   • schemaName：所用的工作流
   • planningHome、changeRoot、artifactPaths 和 actionContext：路径和范围上下文
   • artifacts：产物列表及其状态（done、skipped 或其他） 如果任何工件既不是 done 也不是 skipped（跳过的工件符合要求——变更声明了 skip_specs）：
   • 显示警告并列出未完成的工件
   • 询问用户是否确认继续
   • 如果用户确认，则继续

3. 检查任务完成状态

   读取任务文件（通常为 tasks.md），检查是否有未完成的任务。

   统计标记为 - [ ]（未完成）和 - [x]（已完成）的任务。

   如果发现未完成的任务：

   • 显示警告并说明未完成任务的数量
   • 询问用户是否确认继续
   • 如果用户确认，则继续

   如果不存在任务文件： 继续，不显示与任务相关的警告。

4. 评估差异规范的同步状态

   将状态 JSON 中的 artifactPaths.specs.existingOutputPaths 作为唯一的 差异规范来源。如果缺少 specs 条目，或 existingOutputPaths 为空，则继续，不询问同步事宜，也不要从其他工件推断 差异规范。

   如果存在差异规范：

   • 将每个差异规范与对应的主规范进行比较，路径为 <planningHome.root>/openspec/specs/<capability-path>/spec.md（使用步骤 2 中支持存储区的 planningHome.root，不要硬编码仓库路径）
   • 确定将应用哪些变更（新增、修改、移除、重命名）
   • 在提示用户之前显示合并后的摘要

   提示选项：

   • 如果需要变更："立即同步（推荐）"、"不经同步直接归档"
   • 如果已同步："立即归档"、"仍然同步"、"取消"

   根据用户的回答采取操作：

   • "取消"——停止，不要归档
   • "不经同步直接归档"或"立即归档"——继续归档
   • "立即同步"或"仍然同步"——同步，然后验证（如下）
   • 其他任何回答——再次询问，不要归档

   在所选同步写入任何主规范之前，使用相同的 所选根目录标志运行一次 openspec instructions specs --change "<name>" --json。要求命令退出状态为 0，且返回有效的工件指令 JSON。如果查找失败或返回无效 JSON，则报告错误并停止，不得写入任何主规范或移动变更。如果有效响应中未提供 rules，则视为无规则情况。仅将返回的 rules 应用于本次合并生成的主规范内容及形式；不得将其用作归档指导、改变 CLI 行为，或将规则文本复制到任何输出文件中。

   随后，针对变更 '' 内联运行 openspec-sync-specs 工作流（由 Agent 驱动的智能合并），传入上述差异规范分析和已获取的 specs 规则快照，并等待其完成。内联同步必须复用该快照，不得再次获取 specs 指令。不要将其委派给后台任务——步骤 5 会在同步仍在读取 changeRoot 时将其移走，导致变更已归档而主规范尚未更新。如果你的 Agent 只能通过委派来运行，则必须同步委派并等待结果。

   然后，针对 artifactPaths.specs.existingOutputPaths 中每个包含差异规范的能力，重新从本步骤开头执行比较，而不只是检查同步报告中处理过的能力。成功同步后，不应再有待应用的变更，因此每项能力现在都必须显示为已同步：

   • ADDED 要求已存在
   • MODIFIED 要求包含差异中指定的场景和描述变更，同时保留其其他场景
   • REMOVED 要求已移除；如果此次同步停用了某项能力（移除了其最后一项要求，导致 ## Requirements 为空），则必须删除其主规范，而不是保留空文件；同步明确保留并报告的规范也视为匹配
   • RENAMED 要求以新名称存在，且旧名称已不存在

   如果同步失败，或任何能力不匹配，则报告差异并停止——不要归档。此时尚未移动任何内容，且 changeRoot 完整无损，因此用户可以修复差异或重新运行同步，然后重新开始归档。

5. 执行归档 如果 planningHome.changesDir 下不存在 archive 目录，则创建它：

   mkdir -p "<planningHome.changesDir>/archive"
   

   生成目标名称：如果变更名称已以 YYYY-MM-DD- 前缀开头，则保持原样；否则在前面加上当前日期，格式为 YYYY-MM-DD-<change-name>。绝不叠加第二个日期（规则与 openspec archive 相同）。

   检查目标是否已存在：

   • 如果存在：报错，并建议重命名现有归档或使用其他日期
   • 如果不存在：将 changeRoot 移动到归档目录

   mv "<changeRoot>" "<planningHome.changesDir>/archive/<target-name>"
   

6. 显示摘要

   显示归档完成摘要，包括：

   • 变更名称
   • 使用的 Schema
   • 归档位置
   • 是否已同步规范（如适用）
   • 关于任何警告的说明（未完成的制品/任务）

成功时的输出

## Archive Complete

**Change:** <change-name>
**Schema:** <schema-name>
**Archived to:** the archive path derived from `planningHome.changesDir`/<target-name>/
**Specs:** <"✓ Synced to main specs" only if the step 4 verification passed; otherwise "No delta specs" or "Sync skipped">

<"All artifacts complete. All tasks complete." — or, if archived with warnings, list them instead (e.g. "Archived with 2 incomplete tasks")>

防护措施

• 宣布选中的变更；如果选择存在歧义，则提示用户选择
• 使用制品图（openspec status --json）检查完成情况
• 不要因警告而阻止归档——只需告知并确认
• 移动到归档时保留 .openspec.yaml（它会随目录一起移动）
• 清晰展示操作结果摘要
• 如果请求同步，则在流程内运行 openspec-sync-specs 工作流（由 Agent 执行）
• 规范同步仍在进行时绝不归档——在流程内运行同步，并在移动 changeRoot 前验证主规范
• 如果存在增量规范，始终运行同步评估，并在提示前展示综合摘要
• 应用相关运行时上下文并报告冲突；操作指导仅供参考
• 考虑每条指导内容，并说明任何不适用或冲突之处
• 现有 CLI 检查、解析后的路径、提示和命令约定保持不变
• 制品规则仅约束正在编写的规范，绝不是操作指导
• 绝不将运行时上下文、操作指导或制品规则文本原样复制到输出文件