SuperBizAgent-java/.claude/skills/sm-flow/references/archive-rules.md

归档规则

archive 阶段的目标是把 OpenSpec 产物、实现结果和过程日志转化为持久、可读、可复用的项目记忆。sm-flow 在 clarify → apply 期间只维护 decisions.md 作为过程日志，archive 阶段从中提取完整 devflow 档案。

目录规则

项目档案路径：

devflow/projects/YYYY-MM-DD-{slug}/

archive 阶段创建以下文件：

• brief.md：从 proposal.md 提取背景、目标、范围、非目标。
• evidence.md：从 decisions.md 中的 evidence-driven 记录提取。
• decisions.md：保持为最终版，整理格式。
• acceptance.md：从实现结果和验证结果提取。

同时维护仓库级索引：

• devflow/index.md

按需创建以下扩展文件：

• prd.md
• research.md
• design.md
• tasks.md
• alignment.md
• adr/*.md

不要逐字复制完整 OpenSpec 文件，也不要重复 OpenSpec 的 proposal/design/tasks。应提炼 OpenSpec 如何指导执行：背景、证据、用户决策、任务状态、假设、验证结果、风险，以及执行中对 OpenSpec 的修正。

产物分档

分档	适用场景	必须文件	扩展文件
micro	小改动、低风险、需求明确	brief.md、decisions.md、acceptance.md	证据少时并入 brief.md
standard	默认模式	brief.md、evidence.md、decisions.md、acceptance.md	按需 ADR/compound
complex	高风险、跨模块、需求不清、多人协作	standard 全部文件	按需 prd.md、research.md、design.md、tasks.md、alignment.md

提取映射

来源	提取内容	写入位置
decisions.md（过程日志）	question pool、evidence-driven 汇报状态、user-interview 确认状态、关键取舍	decisions.md（整理格式为最终版）
decisions.md（过程日志）	evidence-driven 结论、代码/文档证据	evidence.md
proposal.md	为什么做、做什么、范围、非目标	brief.md
design.md	技术方案、关键决策、风险；只提炼长期有用内容	evidence.md / 按需 design.md
specs/**/*.md	requirement 标题和 scenario 意图	brief.md 或 acceptance.md 的验收追踪
tasks.md	checkbox 状态、剩余工作、执行切片	acceptance.md；复杂项目可拆 tasks.md
测试/构建输出	验证命令、结果、验证类型	acceptance.md
diagnose 记录	根因、修复、回归验证	acceptance.md
词汇表更新	术语和业务规则	devflow/glossary/CONTEXT.md
可复用经验	持久工程知识	devflow/compound/YYYY-MM-DD-{type}-{slug}.md
项目索引	日期、slug、领域、关键词、关联 OpenSpec、状态	devflow/index.md

索引维护规则

devflow/index.md 是 context 阶段的默认入口，archive 阶段回填时必须维护。

最小字段：

日期	slug	领域	关键词	关联 OpenSpec	状态

规则：

• 每个 devflow/projects/YYYY-MM-DD-{slug}/ 默认对应一行索引。
• archive 阶段新建或更新项目档案时，必须新增或更新对应行。
• 如果项目仍在进行，状态写 active；已验收但未 archive 写 accepted-unarchived；已 archive 写 archived；暂停写 paused。
• 关键词只放能帮助 context 阶段定位的术语，不复制 brief 内容。
• 如果无法准确判断领域或状态，写 unknown，并在 acceptance.md 记录待补。

验收记录规则

必须真实记录验证情况，并按类型分类：

• 静态验证：语法检查、grep/rg 检查、结构检查、类型检查等不运行完整功能的验证。
• 脚本验证：生成脚本、测试命令、构建命令、自动化检查等可重复命令。
• 浏览器/人工验证：需要用户或代理在界面中点击、观察、确认的行为验证。
• 未验证：未运行的验证必须记录原因、风险和建议补验步骤。

记录要求：

• 如果验证通过，记录命令/步骤和覆盖范围。
• 如果验证失败，记录失败摘要和是否阻塞验收。
• 如果需要人工验证，列出明确步骤，不要用"手动测试一下"这种模糊描述。

ADR 规则

同时满足以下条件时创建 ADR：

1. 决策难以逆转。
2. 缺少上下文会让未来维护者困惑。
3. 决策来自真实权衡，而不是简单偏好。

项目内 ADR 存放于：

devflow/projects/YYYY-MM-DD-{slug}/adr/

跨项目可复用决策或经验存放于：

devflow/compound/YYYY-MM-DD-decision-{slug}.md

归档确认

OpenSpec archive 是显式 human-in-the-loop 动作。archive 前必须确认 devflow 已经回填 OpenSpec 的关键执行信息：

• archive 阶段可以建议 archive，但必须先询问用户。
• 在用户确认前，不要执行 archive。
• 如果用户暂不归档，在 acceptance 中记录原因或状态。
• 如果用户确认归档，执行后记录 archive 结果和剩余档案位置。

归档交接

archive 阶段结束时告诉用户：

• 创建或更新了哪些档案文件。
• devflow/index.md 是否已更新。
• 运行了哪些验证，并按静态验证、脚本验证、浏览器/人工验证、未验证分类。
• 还剩哪些风险或后续事项。
• 明确询问：是否现在 archive OpenSpec change？