f2s-kb-upgrade

执行口径：本技能用于「代替用户跑 shell」完成 按本 SKILL 定义的 Flow2Spec 模板与配置根对齐；其中一步会代跑 flow2spec init，但 init 不是「升级命令」，升级命令 / 知识库升级 仅指 f2s-kb-upgrade 本技能全流程。

f2s-kb-upgrade（知识库模板升级技能）

术语（必须）：「升级」「升级命令」「知识库升级」 仅指按本文件 f2s-kb-upgrade 执行的完整技能流程。flow2spec init 是 CLI 初始化/落盘命令；本技能 步骤 2 会代跑它，禁止把用户单独执行的 init 或 CLI 帮助里的 init 表述为「升级命令」。

边界（避免误区）

• flow2spec init 不写业务知识：不替代 f2s-kb-add、f2s-kb-fix、f2s-kb-feat、f2s-kb-sync、f2s-kb-build 等对 stock-docs / req-docs / topics 正文与业务向路由词条的维护。
• 本技能跑通的是 包版本下的目录、模板占位、路由结构对齐；用户若说「把新能力写进知识库」，应引导 f2s-kb-sync / f2s-kb-add 等，而非仅 f2s-kb-upgrade。
• 本技能负责存量 topicMetadata 审计：primary / tags 仅用于治理、审计、盘点和阅读预期，不参与路由命中或执行强制性；执行强制性仍以 AGENTS.md、rules、skills 与 topic 正文为准。

包侧发版纪律（projectRev 必须正确 bump）

字段位置：templates/{zh-CN,en-US}/knowledge/manifest-routing.json 的根级整数字段 projectRev（起始 1）。

字段写入语义（必读）：

• 包侧：维护者按下文规则手动 bump（包模板自身的 projectRev 永远是最新值）。
• 项目侧（落盘到 .Knowledge/manifest-routing.json）：
  • 首次 init：项目 .Knowledge/manifest-routing.json 不存在 → init 把模板原值落盘，等同首次落地即基线对齐。
  • 后续 init：项目 .Knowledge/manifest-routing.json 已存在 → init 不再覆盖该字段（保留项目原值）；该字段只由本技能完整流程末尾 3b 写入（见步骤 3b「回写 projectRev」）。
  • 这使「项目侧 projectRev」语义清晰：「本项目已基线对齐到的包模板修订号」，而非"上次 init 时碰到的"。

必须 bump 的修改（每次发版至少 +1）：

• 包模板 templates/<locale>/knowledge/topics/<topic>.md 任一文件的正文修改、新增、删除或改名；
• 包模板 templates/<locale>/knowledge/matchers/<id>.json 的 includeAny 词条、id 或新增 / 删除 matcher 文件；
• 包模板 templates/<locale>/knowledge/manifest-routing.json 的 topicPaths / taskToTopicRules / topicDependencies / fallbackTopic / topicMetadata 任一段修改；
• 包模板 templates/<locale>/knowledge/index.md 「主题一览」节或包级章节修改。

不需要 bump 的修改：

• 包源码（lib/、cli.js、scripts/）、AGENTS.md、README* 文档；
• templates/<locale>/flow2spec.config.json 默认值；
• templates/<locale>/rules/* / templates/<locale>/skills/* 仅规则与技能正文修改（这些与主题层无关，无需触发完整流程）。

判定准则一句话：模板里 knowledge/ 目录下 topic / matcher / manifest / index 任一主题层产物变了 → 必 bump；否则不动。漏 bump 会让用户的 f2s-kb-upgrade 跑快速路径，错过包带来的主题变更。