| name | f2s-doc-milestone |
| description | 据 req-docs、git log、.task 与知识库主题语义生成里程碑（《项目里程碑模版》）；触发：f2s-doc-milestone、生成项目里程碑、里程碑。命令后可附语义化范围。本技能固定子 agent 生成、主 agent 验证，不受 flow2spec.config 编排开关影响 |
执行口径：读 .Knowledge/template/项目里程碑模版.md；落盘 仅 .Knowledge/stock-docs/<范围名>里程碑.md（无第二路径参数）。
编排（固定，不受项目配置影响）
本技能不受 flow2spec.config.json 中 subAgent、switchAgentVerification（及旧键 subAgentVerification）影响：无论其为 true 或 false，一律按下述分工执行，禁止因配置改为「全主会话」或「子 agent 自验即结束」。
| 角色 | 步骤 | 职责 |
|---|
| 主 agent | 0、3、4 | 读模版与知识库主题索引、解析范围、派子、验证、必要时修订、回复用户 |
| 子 agent | 1、2 | 采集四源、套模版、Write 初稿 |
- 主 agent：步骤 0 → 下发「采集契约」→ 子 agent 步骤 1–2 落盘初稿。
- 主 agent：步骤 3 对照四源与「重要节点清单」验证（不全文重写；补缺、纠偏、「待确认」）→ 步骤 4 回复。
- 子 agent 禁止宣称「里程碑已验收完成」；终稿以主 agent 验证后为准。
步骤 0 仍 Read("flow2spec.config.json")（满足 f2s-config-check 前置），但不得用其中的 subAgent / switchAgentVerification 改变本技能编排。
子 agent 采集契约（主 agent 派子前写入 prompt）
| 字段 | 内容 |
|---|
scope | 用户语义范围一句 |
outputPath | stock-docs/<范围名>里程碑.md |
sources | 见下文「四源」；须含知识库主题语义 |
template | .Knowledge/template/项目里程碑模版.md（不写模版顶部说明 blockquote） |
delivery | 完整 Markdown，可直接 Write 至 outputPath |
stagePolicy | 见下文「阶段粒度」；契约中须复述一句 |
阶段粒度（必须，写入契约）
里程碑 Mx 仅记录功能/能力变更：当前仓库（或用户指定范围内）已落地或可核验的交付，例如模块/接口/数据模型/领域行为/知识库路由等，且须在四源中有依据。
不得单独占一行总览或独立 ## Mx · 的阶段类型（无四源交付支撑时禁止臆造；有交付也不得拆成「纯测试/纯联调」阶段）：
- 联调、集成测试、UAT、回归、验收、提测、上线检查（仅过程、无功能 diff）
- 仅环境/运维动作（执行 DDL、填配置、发版窗口、跨仓排期）且无本范围功能交付
- 以「稳定化 / 工程化 / 收尾」为名、实质仅为上述过程性工作的阶段
合并规则：同一次能力迭代内的工程性改动（如 id 类型对齐、分页格式、锁与并发）并入对应功能阶段正文，不另起「联调 / 测试 / 验收」阶段。
缺口处理：四源仅提及待联调、待验收、环境待补齐而无本范围功能交付 → 不写对应 Mx；可在 待确认 列一句，禁止用「计划项」填充总览表。
四源（采集与验证均须覆盖）
| 源 | 读什么 | 里程碑里怎么用 |
|---|
| req-docs | 范围内 .Knowledge/req-docs/*.md | 需求/方案节点、交付摘要 |
| git | git log --no-merges、git tag -l、package.json 版本 | 时间线、大版本/tag、提交锚点 |
.task | todo.json、active/、completed/ 下 task.md 等 | 任务闭环、已交付步骤 |
| 知识库主题（语义） | 见下「主题索源」 | 与 index/manifest 已登记能力对齐，避免漏写「库里已有语义」的阶段 |
主题索源（知识库语义，主 agent 步骤 0 须读；子 agent 步骤 1 须读）
Read(".Knowledge/manifest-routing.json")：提取 topicPaths、taskToTopicRules（及与范围相关的 topicDependencies）。Read(".Knowledge/index.md")：至少「主题一览」表（主题 id、适用场景、关联文档摘要）。- 按需
Read .Knowledge/topics/<topic>.md：与范围或 manifest 命中相关的摘要（禁止为枚举遍历整个 topics/；仅读 manifest/index 已点名的主题，通常 ≤ 全表行数）。
- 将主题语义归纳为「能力/场景节点」列表，供子 agent 写入契约；里程碑阶段须能覆盖或于「待确认」说明与某主题相关的缺口。
索源内容仅用于采集与验证，禁止写入生成文档；生成文档不含「索源」行、topic 路径或 manifest 内部名称。
入参（仅一个，可选）
命令名之后可跟一段语义化范围（自然语言）：
| 用户意图 | 示例 | 落盘文件名 |
|---|
| 整个项目（默认） | 不传 / 整个项目 / 全项目 | 项目里程碑.md |
| 某一需求或能力 | 回调改造 / 登录模块 | <简述>里程碑.md |
文件名规则：后缀 里程碑.md；整个项目 → 前缀 项目；单一需求 → 语义或 req 标题简述（≤ 20 字）。
范围收窄：在四源上按关键词、路径、日期过滤；未传范围则四源全量可追溯（主题索源读 index 全表 + manifest，topics 按需展开）。
步骤 0：前置（主 agent）
Read("flow2spec.config.json")（不采纳其 subAgent / switchAgentVerification 编排本技能）Read(".Knowledge/template/项目里程碑模版.md")- 主题索源（见上：manifest → index 主题一览 → 按需 topics 摘要）
- 解析范围 → 确定默认路径
stock-docs/<范围名>里程碑.md。
- 相似文件检查（落盘前必做）：列出
.Knowledge/stock-docs/ 下已有 *里程碑*.md（含 *里程碑.md）。若存在与本次目标路径相同或语义相近的文件（例如同为「整个项目」的 项目里程碑.md 与另一份全项目里程碑、或前缀/范围关键词高度重叠），须先询问用户，禁止静默覆盖或擅自另存：
- 覆盖：沿用原路径，子 agent 写入时覆盖该文件（验证后仍以该路径为终稿）。
- 另生成一份：改用新路径（建议：范围简述 +
_YYYYMMDD + 里程碑.md，或用户指定的 <简述>里程碑.md），并在契约中更新 outputPath。
- 无相似文件，或仅有一个且与目标路径完全一致且用户本轮已明确要「重新生成/覆盖」→ 可不再追问，按默认路径继续。
- 向用户复述：范围、最终
outputPath、已读主题数量；若做了相似文件询问，待用户选择后再继续。
- 组装「采集契约」（含最终
outputPath、主题节点列表）并 派子 agent 执行步骤 1–2
步骤 1：采集索源（子 agent）
- 按契约完成 四源 采集；git 须 对照 tag 与主版本/semver 跃迁（以本仓库
git tag / package.json 为准）。
- 主题语义：核对 manifest/index 中能力与 git/req/task 是否同窗出现；暂无法对齐的记入内部备注供「待确认」。
索源为空：仍生成文档，「待确认」说明缺口；禁止训练数据填交付。
步骤 2：套模版并落盘（子 agent）
生成原则：面向读者，不暴露内部信息。
- 文首只写：标题
# （范围名）里程碑、范围、更新时间。不写 索源行、topic 路径、manifest 内部名称、commit hash、npm 发布状态、环境状态等任何内部信息。
- 阶段倒序：总览表与各
## Mx · 均按最新在前排列（MN → … → M1）；每阶段标题体现功能变更，不得用「联调 / 测试 / 验收」命名（见「阶段粒度」）。
- 每阶段正文：仅列已交付的功能点，每条一行，可验证；不写时间细节、过程说明或背景铺垫。
- 待确认：只列功能/交付层面的缺口或不一致；禁止写内部运维/发布/环境状态。若无缺口写「无」。
- 不写模版顶部说明 blockquote。
Write 至 outputPath。
步骤 3：验证（主 agent，须执行）
子 agent 落盘后 必须验证：重要节点是否错误、遗漏或合并过度。
- 重读四源要点：git tag/commit、req/task、index 主题一览 + 已读 topics 与文稿对照。
- 对照「重要节点清单」：
| 类别 | 检查什么 |
|---|
| 版本 / tag | 四源中的 major tag、package.json 版本跃迁是否在总览或 Mx 中体现 |
| 路线/架构转折 | 四源中出现的目录重组、技术路线替换等重大变更是否单独或合并体现 |
| 功能交付 | req/git/task 中可核验的能力是否在 Mx 中有对应阶段 |
| 知识库主题 | 若存在 manifest/index：与范围相关的主题是否覆盖或列入「待确认」 |
| 任务闭环 | 若存在 .task/：已归档任务是否在相关 Mx 中体现 |
| 依据可追溯 | 每 Mx 交付能否在四源中找到 |
| 时间线 | 先后合理；同窗多版本是否需拆分 |
| 排序 | 总览表与各 Mx 是否均为最新在前；若不是则调整 |
| 阶段粒度 | 是否存在仅联调/测试/验收/环境而无功能交付的 Mx；若有 删除或并入 相邻功能阶段 |
| 内部信息 | 文档中是否含索源行、commit hash、topic 路径、npm/环境状态等内部信息；若有删除 |
- 遗漏 → 补 Mx（须为功能变更）；错误 → 按四源修正；无法确认 → 「待确认」（禁止用假 Mx 代替）。
- 验证或修订完成后方可步骤 4。
步骤 4：回复（主 agent）
落盘路径、阶段数、验证结论（一句）、「待确认」摘要。
禁止项
- 禁止用
subAgent / switchAgentVerification 跳过子生成或跳过主验证。
- 禁止在
stock-docs/ 已存在相似里程碑且用户未选择「覆盖 / 另生成一份」前派子 agent 或 Write。
- 禁止第二参数改输出路径（路径由范围 + 相似文件询问结果确定）；禁止写入
req-docs。
- 禁止未读四源写交付；禁止子 agent 未经验证即宣称完成。
- 禁止遍历整个
matchers/ 或全仓 topics 代替「manifest + index + 按需 topics」。
- 禁止用训练数据或其它项目的里程碑结构替代当前仓库四源；禁止代写与本次
outputPath 无关的其它 stock-docs 文档。
- 禁止单独设立联调 / 集成测试 / UAT / 验收 / 纯环境运维类 Mx；禁止在无四源功能交付时写「计划项」阶段。
