f2s-doc-milestone

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 初稿

1. 主 agent：步骤 0 → 下发「采集契约」→ 子 agent 步骤 1–2 落盘初稿。
2. 主 agent：步骤 3 对照四源与「重要节点清单」验证（不全文重写；补缺、纠偏、「待确认」）→ 步骤 4 回复。
3. 子 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 须读）

1. Read(".Knowledge/manifest-routing.json")：提取 topicPaths、taskToTopicRules（及与范围相关的 topicDependencies）。
2. Read(".Knowledge/index.md")：至少「主题一览」表（主题 id、适用场景、关联文档摘要）。
3. 按需 Read .Knowledge/topics/<topic>.md：与范围或 manifest 命中相关的摘要（禁止为枚举遍历整个 topics/；仅读 manifest/index 已点名的主题，通常 ≤ 全表行数）。
4. 将主题语义归纳为「能力/场景节点」列表，供子 agent 写入契约；里程碑阶段须能覆盖或于「待确认」说明与某主题相关的缺口。

索源内容仅用于采集与验证，禁止写入生成文档；生成文档不含「索源」行、topic 路径或 manifest 内部名称。

入参（仅一个，可选）

命令名之后可跟一段语义化范围（自然语言）：

用户意图	示例	落盘文件名
整个项目（默认）	不传 / 整个项目 / 全项目	项目里程碑.md
某一需求或能力	回调改造 / 登录模块	<简述>里程碑.md

文件名规则：后缀 里程碑.md；整个项目 → 前缀 项目；单一需求 → 语义或 req 标题简述（≤ 20 字）。

范围收窄：在四源上按关键词、路径、日期过滤；未传范围则四源全量可追溯（主题索源读 index 全表 + manifest，topics 按需展开）。

步骤 0：前置（主 agent）

1. Read("flow2spec.config.json")（不采纳其 subAgent / switchAgentVerification 编排本技能）
2. Read(".Knowledge/template/项目里程碑模版.md")
3. 主题索源（见上：manifest → index 主题一览 → 按需 topics 摘要）
4. 解析范围 → 确定默认路径 stock-docs/<范围名>里程碑.md。
5. 相似文件检查（落盘前必做）：列出 .Knowledge/stock-docs/ 下已有 *里程碑*.md（含 *里程碑.md）。若存在与本次目标路径相同或语义相近的文件（例如同为「整个项目」的 项目里程碑.md 与另一份全项目里程碑、或前缀/范围关键词高度重叠），须先询问用户，禁止静默覆盖或擅自另存：
   • 覆盖：沿用原路径，子 agent 写入时覆盖该文件（验证后仍以该路径为终稿）。
   • 另生成一份：改用新路径（建议：范围简述 + _YYYYMMDD + 里程碑.md，或用户指定的 <简述>里程碑.md），并在契约中更新 outputPath。
   • 无相似文件，或仅有一个且与目标路径完全一致且用户本轮已明确要「重新生成/覆盖」→ 可不再追问，按默认路径继续。
6. 向用户复述：范围、最终 outputPath、已读主题数量；若做了相似文件询问，待用户选择后再继续。
7. 组装「采集契约」（含最终 outputPath、主题节点列表）并 派子 agent 执行步骤 1–2

步骤 1：采集索源（子 agent）

• 按契约完成 四源 采集；git 须 对照 tag 与主版本/semver 跃迁（以本仓库 git tag / package.json 为准）。
• 主题语义：核对 manifest/index 中能力与 git/req/task 是否同窗出现；暂无法对齐的记入内部备注供「待确认」。

索源为空：仍生成文档，「待确认」说明缺口；禁止训练数据填交付。

步骤 2：套模版并落盘（子 agent）

生成原则：面向读者，不暴露内部信息。

1. 文首只写：标题 # （范围名）里程碑、范围、更新时间。不写 索源行、topic 路径、manifest 内部名称、commit hash、npm 发布状态、环境状态等任何内部信息。
2. 阶段倒序：总览表与各 ## Mx · 均按最新在前排列（MN → … → M1）；每阶段标题体现功能变更，不得用「联调 / 测试 / 验收」命名（见「阶段粒度」）。
3. 每阶段正文：仅列已交付的功能点，每条一行，可验证；不写时间细节、过程说明或背景铺垫。
4. 待确认：只列功能/交付层面的缺口或不一致；禁止写内部运维/发布/环境状态。若无缺口写「无」。
5. 不写模版顶部说明 blockquote。
6. Write 至 outputPath。

步骤 3：验证（主 agent，须执行）

子 agent 落盘后 必须验证：重要节点是否错误、遗漏或合并过度。

1. 重读四源要点：git tag/commit、req/task、index 主题一览 + 已读 topics 与文稿对照。
2. 对照「重要节点清单」：

类别	检查什么
版本 / tag	四源中的 major tag、package.json 版本跃迁是否在总览或 Mx 中体现
路线/架构转折	四源中出现的目录重组、技术路线替换等重大变更是否单独或合并体现
功能交付	req/git/task 中可核验的能力是否在 Mx 中有对应阶段
知识库主题	若存在 manifest/index：与范围相关的主题是否覆盖或列入「待确认」
任务闭环	若存在 .task/：已归档任务是否在相关 Mx 中体现
依据可追溯	每 Mx 交付能否在四源中找到
时间线	先后合理；同窗多版本是否需拆分
排序	总览表与各 Mx 是否均为最新在前；若不是则调整
阶段粒度	是否存在仅联调/测试/验收/环境而无功能交付的 Mx；若有 删除或并入 相邻功能阶段
内部信息	文档中是否含索源行、commit hash、topic 路径、npm/环境状态等内部信息；若有删除

3. 遗漏 → 补 Mx（须为功能变更）；错误 → 按四源修正；无法确认 → 「待确认」（禁止用假 Mx 代替）。
4. 验证或修订完成后方可步骤 4。

步骤 4：回复（主 agent）

落盘路径、阶段数、验证结论（一句）、「待确认」摘要。

禁止项

• 禁止用 subAgent / switchAgentVerification 跳过子生成或跳过主验证。
• 禁止在 stock-docs/ 已存在相似里程碑且用户未选择「覆盖 / 另生成一份」前派子 agent 或 Write。
• 禁止第二参数改输出路径（路径由范围 + 相似文件询问结果确定）；禁止写入 req-docs。
• 禁止未读四源写交付；禁止子 agent 未经验证即宣称完成。
• 禁止遍历整个 matchers/ 或全仓 topics 代替「manifest + index + 按需 topics」。
• 禁止用训练数据或其它项目的里程碑结构替代当前仓库四源；禁止代写与本次 outputPath 无关的其它 stock-docs 文档。
• 禁止单独设立联调 / 集成测试 / UAT / 验收 / 纯环境运维类 Mx；禁止在无四源功能交付时写「计划项」阶段。