plan-milestones

规划里程碑

编写并维护 docs/roadmap/INDEX.md——连接产品愿景与单个功能规范的规划层：有哪些里程碑、顺序如何、各自涵盖哪些工作，以及哪些已正式承诺。所处位置：define-project（愿景）→ plan-milestones（里程碑）→ frame-change → specify-behavior → … 规划条目一旦由 specify-behavior 注册到 docs/specs/INDEX.md，就会成为一个功能；specify-behavior 是唯一负责登记功能代码的环节，而本技能绝不会接触该文件。

铁律

THE ROADMAP RECORDS INTENT. PROGRESS IS DERIVED, NEVER STORED HERE.

意图是工具无法自行推断的内容：里程碑承诺的成果、顺序、所属工作、延期内容及其原因，以及人是否已作出承诺。进度已经记录过一次——作为每个功能自身 requirements.md 中的 Status:，并同步到 docs/specs/INDEX.md 对应行；在此重复记录只会逐渐偏离唯一来源（原因见「合理化借口」）。

因此，此文件不得包含进度列、状态字段、变更日志或完成百分比；/refresh-roadmap-status 会按需从规范和 Git 中推导当前情况。 Commitment 不代表进度：Planned | Committed | Closed 记录的是人作出的决定，无法通过推断得出——保留此字段，不得保留任何跟踪进度的内容。

模式

• create——不存在 docs/roadmap/INDEX.md。编写该文件。
• update——文件已存在。根据变更信号修订。

按以下顺序解析包模板，使用第一个存在的路径：(1) 与此 SKILL.md 同目录的 templates/；(2) 设置了 ${CLAUDE_PLUGIN_ROOT} 时，使用 ${CLAUDE_PLUGIN_ROOT}/templates；(3) 相对于此 SKILL.md 的 ../../../templates。templates/roadmap-INDEX.md 中的每个标题都是必填项——填写内容或写 None。其中的注释块包含权威的结构规则 S1–S8 和 ID 规则；请阅读该处内容，不要在别处重复陈述。

创建

1. **阅读输入：**若存在 docs/product/vision.md，阅读其中里程碑引用的 **GOAL-N** ID；阅读 docs/specs/INDEX.md，因为棕地项目中已交付的工作应归入早期里程碑，而不应无处归属；并阅读从 frame-change 获得的任何任务分解。 完成标准：能够说出涉及的目标和已交付的工作。
2. 填写模板并写入 docs/roadmap/INDEX.md。每个里程碑使用一个 MILE-N；每个条目使用一个 ROAD-N，归属且只归属一个里程碑，并以 ID 和 slug 标识。 完成标准：每个必填项都已填写或标为 None。
3. 按用户价值分组。 里程碑的 Outcome: 用一句话说明交付后用户能做什么；没有看过代码的读者也应能验证该结果。若成果只能表述为执行了某项工作（“重写存储层”），那它属于技术层，而非里程碑——应将其纳入它所支持的里程碑。设计已确定时，优先采用更少、规模更大的里程碑；若早期反馈可能改变后续方向，则拆分里程碑。 完成标准：每个里程碑都有可验证的成果。
4. **引用目标。**若存在愿景，每个里程碑的 Goals: 都应列出其服务的有效 GOAL-N ID；未被任何里程碑引用的每个有效目标，都应在 ## Goal dispositions 下标记为 Deferred 或 Out-of-scope，并注明日期及原因。若不存在愿景，则填写 Goals: None，并将处置表留空。 完成标准：所有有效目标均有归属，或不存在愿景。
5. **声明顺序和涉及范围。**每个条目的 After: 应按模板格式说明其依赖项，或填写 none。Surfaces: 应列出预期会涉及的组件或路径；若涉及范围暂时无法确定，则填写 None 并说明原因。 完成标准：每个条目都有 After: 和 Surfaces: 行。
6. 执行 ## 审批关卡。

更新

变更信号包括新增里程碑、调整顺序、变更范围、作出承诺、关闭事项，或不再需要某个条目。

每个受影响里程碑中的每个成员都要按模板格式写上 After:，以此表示重新排序；只要出现 After:，列表位置就不再表示顺序。

文件中已有的每个 ID 都是永久的。 调整表格顺序只会改变排列，不会改变 ID；移到其他里程碑的条目保留其 ROAD-N。只有用删除线标记并说明原因才能退役某个 ID，例如 ~~**ROAD-4**~~ dropped 2026-07-25: no custom search UI，这样历史记录仍然清晰，也不会留下悬空引用。不再需要的条目应延期，而非删除：将其移到所属里程碑的 Deferred: 位置，并注明日期和原因；删除该行会毁掉唯一一条能证明曾考虑过此选项的记录（参见 Rationalizations）。

对 Approved 路线图作出实质性变更，会使其降级。 将 Status: Draft，然后重新运行关卡。实质性变更包括任何里程碑的结果、成员、顺序、承诺状态或目标引用变更（为何编辑后不能保留预批准状态，参见 Rationalizations）。

关闭里程碑——仅适用于 Committed → Closed 转换，其他任何编辑都跳过此步骤——表示该里程碑已交付，但本文件本身无法证明这一点。

如果没有评估交接信息就进行 `Committed → Closed` 转换，必须拒绝，并告知用户运行 `/assess-milestone`。此规则适用于所有代码库，包括从未运行过该技能的代码库。

收到写入交接信息——包括一个 MILE-N、评估序号、有效判定结果和候选关闭修订 SHA——后，必须通过读取 docs/roadmap/assessments/<MILE-N>.md，在该序号处重新推导每个值。写入交接信息中的值只是待核实的声明，不能视为可信事实。核实以下五项：

1. 区块中写明的是同一个 MILE-N；
2. 所引用的序号确实存在；
3. 其中的 Candidate closing revision 与写入交接信息中的 SHA 相同；
4. 当前的 Human disposition 为终态（Accepted 或 Overridden）；
5. 有效判定结果和 Close decision 与写入交接信息中的声明一致。

任何一项不符 → 拒绝关闭，并报告具体哪项值不一致。首先依据 templates/milestone-assessment.md 中的 A1–A7 进行验证；无法解析的评估不得作为授权依据。

通过关卡后，读取本文件旁的 closure-writeback.md，并严格遵循其中说明——该文件涵盖写入 Closed: SHA 以及重新运行批准关卡。

完成条件：变更已应用、没有 ID 被移动或消失，并且已运行关卡。

批准关卡

当 docs/agents/issue-tracker.md 中的 Draft surface 为 notion 时，在运行此关卡前，先读取本文件旁的 notion-draft.md 并遵循其中说明：由签核角色批准该页面。

根据模板的规则区块验证 S1–S8。报告发现的每个缺陷，然后停止——存在结构性缺陷的路线图不能提交给用户批准。文件无误后，完整呈现并停止。只有在用户明确批准后，才能写入 `Status: Approved`。对话中的同意不等于批准；由你自行批准的路线图从未真正获批。

按清单逐项检查 S1–S8，指出每个缺陷及其位置，然后呈现文件并停止。用户批准后，将 Status: Approved；用户需要时，/refresh-roadmap-status 会报告计划进展。

完成条件：S1–S8 检查无误、用户已批准所写文件，且 Status: 为 Approved。

ROAD-N 是一个槽位，而不是一项功能

这条规则的唯一归属（其他技能应指向此处；不要在别处重述此表）。

	ROAD-N（项目槽位）	功能 CODE（交付单元）
位于	docs/roadmap/INDEX.md	docs/specs/ + INDEX 行
是否在三阶段流程前存在？	是——尚未编写规格很正常（R7）	仅在 specify-behavior 注册后
进度	此处从不记录	需求中的 Status: / INDEX
关联	—	INDEX 路线图条目 → 每个 ROAD 至多对应一个 CODE（R6）

创建 ROAD 不会创建功能——只有之后 specify-behavior 写入 INDEX 单元格时才会建立关联；slug 文本相同并不会合并 ID。一个里程碑的成果通常需要多个 ROAD 槽位（按成员列表排序），每个槽位在工作开始时关联自己的功能：绝不能把整个里程碑合并到一个 CODE 中，也绝不能为一个 ROAD 创建两个 CODE（R6）。此技能也绝不会创建远程跟踪器项目对象（GitHub 里程碑、Linear initiative、Projects）；此类镜像需通过 configure-repo → docs/agents/issue-tracker.md 中的 Program sync 选择启用，默认仅限本地。

合理化借口

以下各行均为基线运行中的原话，或其直接复现。

想法	事实
“加一列状态就能跟踪进度了”	这只会让它过时。功能进度记录在 requirements.md 的 Status: 中，并镜像到 INDEX 行。/refresh-roadmap-status 会推导出其余状态
“我会添加变更日志，这样状态历史就能保留下来”	这不过是换了个形式的第二份副本。Git 已经保存了此文件的历史
“在里程碑粒度上复用功能生命周期”	Draft → Approved → In-progress → Implemented → Shipped 描述的是一份规格。里程碑承载的是承诺，而不是生命周期
“现在共享更重要了，所以应该叫 MILE-2”	顺序由表格位置决定；身份由 ID 决定。移动行，保留编号
“我重新编号了，这样顺序看起来更自然”	每次重新编号都会在不经意间改变所有引用旧编号的内容所指向的对象
“我们不做这件事了，所以删掉这一行”	将它延期，并注明日期和原因。删除条目也会一并抹去它的理由
“这只是规划文档，所以不需要审批关卡”	正是这个关卡让路线图成为承诺，而不是某人写下的草案。它适用
“用户是审批人，而且他们要求我做这项编辑，所以它仍然是 Approved”	他们要求的是这项编辑，而不是预先批准编辑后的结果。将状态降为 Draft，并让他们看到现在由自己负责的内容
“我两周前已经批准了，这只是一次修订”	修订后的计划是另一份计划，需要单独审批
“这里没有模板，所以我来设计一种格式”	templates/roadmap-INDEX.md 就是规定的格式。两种自创格式无法用同一套规则检查
“ROAD slug 就是功能，所以它们是同一个 ID”	一个是槽位，一个是交付单元。由 INDEX 建立关联；路线图仍然不包含 CODE
“我会为每个 ROAD 创建一个 Linear Project / GH milestone，让看板和路线图保持一致”	这不属于此技能的职责；远程项目同步需选择启用，通常只在功能 issue 上使用正文或标签
“一个里程碑成果 → 一个 ROAD → 一个功能”	一个成果通常需要多个按顺序排列的 ROAD 槽位；每个槽位在工作开始时关联自己的功能

危险信号——立即停止

• 你正要添加用于记录工作进展的列、字段或章节
• 你正要更改文件中已有的编号
• 你正要删除命名某个条目的行，而不是将其延期
• 你正要在用户本次会话尚未表态的情况下写入 Status: Approved
• 你正要在路线图中写入功能代码
• 某个里程碑的成果描述的是已执行的工作，而不是某人能够做的事情
• 你把 ROAD slug 当成功能代码，或在此技能中自行创建 CODE
• 你正要通过此技能创建远程跟踪器项目对象（milestone / initiative / project）

空操作

如果有人要求在 docs/roadmap/INDEX.md 不存在时查阅路线图，请说明项目目前还没有路线图层，并且此技能可以编写路线图，然后停止——路线图层是可选的，没有它也不会阻碍功能流程。