fix(kb): add revision metadata to legacy topics

.Knowledge/index.md

@@ -37,6 +37,7 @@
 | f2s-dev-workflow-constraints | `.Knowledge/topics/f2s-dev-workflow-constraints.md` | 开发工作流约束（仅 Flow2Spec 本仓自身，不给下游）：只改 templates / 不改配置根 / 用户驱动分发 | 长文：`rules/repo-dev-workflow-constraints.*`；自查技能：`skills/repo-dev-check/SKILL.md` |
 | f2s-kb-distill | `.Knowledge/topics/f2s-kb-distill.md` | Q&A 驱动知识提取；自动判断创建新 topic 或追加现有 topic | 技能：skills/f2s-kb-distill/SKILL.mdc |
 | flow2spec-init-defaults | `.Knowledge/topics/f2s-init-defaults.md` | `flow2spec init` 字段默认值、四处落点一致性、老项目缺字段补写、`init` 不动 stock/req/topics/matchers、manifest 两个版本字段（`projectRev` / `pkgRev`）对照 | 包源码：`lib/flow2specConfig.js` `DEFAULTS` / `CONFIG_FIELDS`；模板：`templates/{locale}/flow2spec.config.json` |
+| flow2spec-doctor | `.Knowledge/topics/flow2spec-doctor.md` | `flow2spec doctor` 只读检查环境、项目初始化、协作上下文与知识库健康 | stock：[Doctor 诊断命令](stock-docs/Flow2Spec-doctor诊断命令.md)；中英文命令文档：`docs/命令说明.md` / `docs/en/commands-reference.md` |
 
 每主题保留 **1–3 条** 可点击摘要链接；全量路径对照写入 `.Knowledge/migration-report.md`（迁移场景）。  
 其中 **`implement-tech-design`**、**`f2s-doc-routing`**、**`config-precheck`**、**`f2s-task`** 在 `topics/` 内为**路由摘要**；执行长文见配置根 **`rules/f2s-*.md(c)`**；使用 Codex 时见 **`.codex/AGENTS.md`**、**`.codex/topics/f2s-*.md`**（`f2s-config-check` 与 `AGENTS` 前置同源，按需打开）。**`f2s-knowledge-preflight`** 与 **`f2s-kb-feedback-closing`** 是普通问答首读 / 源码补答收口门禁，作为配置根规则 / Codex 专题长文生效，不写入 `topicPaths` 或 `taskToTopicRules`；**`f2s-kb-feedback-closing`** 在 cases 1–3 建议执行 **`f2s-kb-distill`**。

.Knowledge/manifest-routing.json

@@ -6,8 +6,7 @@
   "fallbackTopic": "fallback-triage",
   "topicDependencies": {
     "implement-tech-design": [
-      "f2s-doc-routing",
-      "stock-docs-vs-req-docs"
+      "f2s-doc-routing"
     ],
     "f2s-req-plan": [
       "f2s-task"
@@ -24,15 +23,15 @@
     "f2s-task": ".Knowledge/topics/f2s-task.md",
     "f2s-req-plan": ".Knowledge/topics/f2s-req-plan.md",
     "f2s-git-commit": ".Knowledge/topics/f2s-git-commit.md",
-    "stock-docs-vs-req-docs": ".Knowledge/topics/f2s-stock-docs-vs-req-docs.md",
     "flow2spec-presentations": ".Knowledge/topics/f2s-flow2spec-presentations.md",
     "flow2spec-milestones": ".Knowledge/topics/f2s-flow2spec-milestones.md",
     "skill-authoring": ".Knowledge/topics/skill-authoring.md",
     "f2s-req-tech": ".Knowledge/topics/f2s-req-tech.md",
     "f2s-dev-workflow-constraints": ".Knowledge/topics/f2s-dev-workflow-constraints.md",
     "f2s-kb-distill": ".Knowledge/topics/f2s-kb-distill.md",
     "flow2spec-init-defaults": ".Knowledge/topics/f2s-init-defaults.md",
-    "flow2spec-collaboration": ".Knowledge/topics/flow2spec-collaboration.md"
+    "flow2spec-collaboration": ".Knowledge/topics/flow2spec-collaboration.md",
+    "flow2spec-doctor": ".Knowledge/topics/flow2spec-doctor.md"
   },
   "taskToTopicRules": [
     {
@@ -49,17 +48,15 @@
       "matcherPath": ".Knowledge/matchers/m-implement-from-spec.json",
       "topics": [
         "f2s-doc-routing",
-        "implement-tech-design",
-        "stock-docs-vs-req-docs"
+        "implement-tech-design"
       ]
     },
     {
       "task": "doc-routing",
       "matcherId": "m-doc-routing",
       "matcherPath": ".Knowledge/matchers/m-doc-routing.json",
       "topics": [
-        "f2s-doc-routing",
-        "stock-docs-vs-req-docs"
+        "f2s-doc-routing"
       ]
     },
     {
@@ -149,6 +146,14 @@
       "topics": [
         "flow2spec-collaboration"
       ]
+    },
+    {
+      "task": "flow2spec-doctor",
+      "matcherId": "m-flow2spec-doctor",
+      "matcherPath": ".Knowledge/matchers/m-flow2spec-doctor.json",
+      "topics": [
+        "flow2spec-doctor"
+      ]
     }
   ],
   "pkgRev": 1,
@@ -221,6 +226,13 @@
       "tags": [
         "policy"
       ]
+    },
+    "flow2spec-doctor": {
+      "primary": "feature",
+      "confidence": "inferred",
+      "tags": [
+        "module"
+      ]
     }
   }
 }

.Knowledge/matchers/m-flow2spec-doctor.json

@@ -0,0 +1,16 @@
+{
+  "includeAny": [
+    "flow2spec doctor",
+    "doctor 命令",
+    "环境诊断",
+    "项目健康检查",
+    "安装检查",
+    "配置检查",
+    "Flow2Spec 诊断",
+    "TASK_ROOT 检查",
+    "知识库健康"
+  ],
+  "id": "m-flow2spec-doctor",
+  "version": "1.0.0",
+  "schema": "flow2spec.matcher.v1"
+}

.Knowledge/stock-docs/Flow2Spec-doctor诊断命令.md

@@ -0,0 +1,42 @@
+# Flow2Spec Doctor 诊断命令
+
+## 定位
+
+`flow2spec doctor` 是面向 Flow2Spec 使用者的只读项目体检入口，用于把分散的环境、初始化、协作和知识库检查汇总成一份可操作报告。首版不提供 `--fix`，不调用网络，也不修改任何项目文件。
+
+## 命令契约
+
+```bash
+flow2spec doctor
+flow2spec doctor --json
+flow2spec doctor --help
+```
+
+- 普通输出逐项显示 `[PASS]`、`[WARN]`、`[FAIL]`，异常项附修复建议。
+- `--json` 输出 `ok`、包信息、当前目录、汇总计数和检查明细，适合脚本或 CI 消费。
+- 警告不阻塞，退出码为 `0`；存在错误时退出码为 `1`。
+- 未知参数直接报错并返回 `1`。
+
+## 检查范围
+
+1. 当前 Node.js 是否满足 `package.json` 的 `engines.node`。
+2. 项目根 `flow2spec.config.json` 是否存在且可解析。
+3. 根 `AGENTS.md` 与 `.Knowledge/manifest-routing.json` 是否存在。
+4. 已存在的 Agent 配置根是否完整：Codex 检查 `.codex/AGENTS.md`、`.codex/hooks.json`；Claude 检查 `.claude/settings.json`；Cursor 检查 `.cursor/hooks.json`。项目没有任何 Agent 配置根时只警告。
+5. 复用 `resolveDeveloperContext` 输出实际 `developerId`、解析来源和 `TASK_ROOT`；无身份回退 legacy `.task/` 时警告。
+6. 根 `.gitignore` 是否显式忽略 `.task/`。
+7. 复用 knowledge engine 做严格知识图校验，并检查 topic revision 与 topic frontmatter 到 routing 元数据的漂移。
+
+## 实现边界
+
+- CLI 分发和参数校验位于 `cli.js`，诊断逻辑与文本格式化位于 `lib/doctor.js`。
+- `lib/doctor.js` 允许测试注入 Node 版本、Git 身份与知识库检查，避免测试依赖开发机全局状态。
+- doctor 只读取项目根已存在的文件；修复动作由用户根据建议显式执行。
+- 旧 topic 缺 `revision` 属严格知识库错误，建议执行 `flow2spec kb build --fix-topics` 后再运行 `flow2spec kb check --strict`。
+- 首版不检查 npm registry 或全局旧包 `@double-codeing/flow2spec`，保持诊断快速、离线、确定。
+
+## 文档入口
+
+- 中文：`docs/命令说明.md` 的 `flow2spec doctor` 章节
+- English: `docs/en/commands-reference.md`, `flow2spec doctor`
+

.Knowledge/topics/f2s-config-precheck.md

@@ -1,3 +1,11 @@
+---
+id: config-precheck
+revision: 0
+summary: "config-precheck（路由摘要）"
+primary: config
+confidence: manual
+tags: [policy]
+---
 # config-precheck（路由摘要）
 
 ## 本主题作用

.Knowledge/topics/f2s-dev-workflow-constraints.md

@@ -1,3 +1,10 @@
+---
+id: f2s-dev-workflow-constraints
+revision: 0
+summary: "f2s-dev-workflow-constraints（路由摘要）"
+primary: policy
+confidence: inferred
+---
 # f2s-dev-workflow-constraints（路由摘要）
 
 > **仅适用于 Flow2Spec 本仓自身**。**不给下游使用**——本 topic 与对应 rules / skill 都**只**存在于本仓，**不进 `templates/`**。

.Knowledge/topics/f2s-fallback-triage.md

@@ -1,3 +1,10 @@
+---
+id: fallback-triage
+revision: 0
+summary: fallback-triage
+primary: policy
+confidence: manual
+---
 # fallback-triage
 
 ## 执行目的

.Knowledge/topics/f2s-flow2spec-milestones.md

@@ -1,3 +1,10 @@
+---
+id: flow2spec-milestones
+revision: 0
+summary: flow2spec-milestones
+primary: feature
+confidence: inferred
+---
 # flow2spec-milestones
 
 ## 执行边界

.Knowledge/topics/f2s-flow2spec-presentations.md

@@ -1,3 +1,10 @@
+---
+id: flow2spec-presentations
+revision: 0
+summary: flow2spec-presentations
+primary: feature
+confidence: inferred
+---
 # flow2spec-presentations
 
 ## 执行边界

.Knowledge/topics/f2s-git-commit.md

@@ -1,3 +1,10 @@
+---
+id: f2s-git-commit
+revision: 0
+summary: "f2s-git-commit（路由摘要）"
+primary: policy
+confidence: manual
+---
 # f2s-git-commit（路由摘要）
 
 > 长文见配置根 **`skills/f2s-git-commit/SKILL.md`**；本仓模板源见 **`templates/skills/f2s-git-commit/SKILL.md`**。

.Knowledge/topics/f2s-implement-tech-design.md

@@ -1,3 +1,11 @@
+---
+id: implement-tech-design
+revision: 0
+summary: "implement-tech-design（路由摘要）"
+dependsOn: [f2s-doc-routing]
+primary: policy
+confidence: manual
+---
 # implement-tech-design（路由摘要）
 
 > **唯一长文**：Cursor / Claude 以配置根 **`rules/f2s-implement-tech-design.md(c)`** 为准。  

.Knowledge/topics/f2s-init-defaults.md

@@ -1,3 +1,11 @@
+---
+id: flow2spec-init-defaults
+revision: 0
+summary: "flow2spec-init-defaults（路由摘要）"
+primary: config
+confidence: inferred
+tags: [policy]
+---
 # flow2spec-init-defaults（路由摘要）
 
 ## 作用

.Knowledge/topics/f2s-kb-distill.md

@@ -1,3 +1,10 @@
+---
+id: f2s-kb-distill
+revision: 0
+summary: "f2s-kb-distill：Q&A 驱动知识提取与入库"
+primary: policy
+confidence: manual
+---
 # f2s-kb-distill：Q&A 驱动知识提取与入库
 
 Q&A 驱动知识提取技能，从普通问答中自动萃取可复用知识事实并入库；根据下钻深度与描述层次自动判断创建新 topic 或追加到现有 topic。

.Knowledge/topics/f2s-req-plan.md

@@ -1,3 +1,11 @@
+---
+id: f2s-req-plan
+revision: 0
+summary: "f2s-req-plan（路由摘要）"
+dependsOn: [f2s-task]
+primary: policy
+confidence: manual
+---
 # f2s-req-plan（路由摘要）
 
 > 长文见配置根 **`skills/f2s-req-plan/SKILL.md`**。  

.Knowledge/topics/f2s-req-tech.md

@@ -1,3 +1,10 @@
+---
+id: f2s-req-tech
+revision: 0
+summary: "f2s-req-tech（路由摘要）"
+primary: policy
+confidence: inferred
+---
 # f2s-req-tech（路由摘要）
 
 > 长文见配置根 **`skills/f2s-req-tech/SKILL.md`**；本仓模板源见 **`templates/skills/f2s-req-tech/SKILL.md`**。

.Knowledge/topics/f2s-stock-docs-vs-req-docs.md

@@ -1,3 +1,10 @@
+---
+id: f2s-doc-routing
+revision: 0
+summary: "f2s-doc-routing（路由摘要）"
+primary: policy
+confidence: manual
+---
 # f2s-doc-routing（路由摘要）
 
 > **唯一长文**：Cursor / Claude 以配置根 **`rules/f2s-stock-docs-vs-req-docs.md(c)`** 为准。  

.Knowledge/topics/f2s-task.md

@@ -1,3 +1,10 @@
+---
+id: f2s-task
+revision: 0
+summary: "f2s-task（路由摘要）"
+primary: policy
+confidence: manual
+---
 # f2s-task（路由摘要）
 
 > 长文见配置根 **`rules/f2s-task.*`**。  

.Knowledge/topics/flow2spec-doctor.md

@@ -0,0 +1,28 @@
+---
+id: flow2spec-doctor
+revision: 0
+summary: "只读检查 Flow2Spec 环境、初始化、协作上下文与知识库健康"
+primary: feature
+confidence: inferred
+tags: [module]
+---
+# Flow2Spec Doctor
+
+## 适用场景
+
+用于回答或维护 `flow2spec doctor`、项目健康检查、环境诊断、初始化完整性、协作上下文和知识库严格校验。
+
+## 已落地能力
+
+- `flow2spec doctor` 输出人读报告；`flow2spec doctor --json` 输出稳定结构。
+- 检查 Node.js、项目配置、Agent 配置根、`developerId` / `TASK_ROOT`、`.task/` 忽略规则与知识图健康。
+- 告警返回 `0`，错误返回 `1`；全程只读、离线，不提供 `--fix`。
+
+## 维护边界
+
+- 命令分发：`cli.js`
+- 诊断实现：`lib/doctor.js`
+- 自动化测试：`scripts/test-doctor.js`
+- 完整事实：`.Knowledge/stock-docs/Flow2Spec-doctor诊断命令.md`
+- 用户文档：`docs/命令说明.md`、`docs/en/commands-reference.md`
+

.Knowledge/topics/skill-authoring.md

@@ -1,3 +1,10 @@
+---
+id: skill-authoring
+revision: 0
+summary: "skill-authoring（路由摘要）"
+primary: policy
+confidence: inferred
+---
 # skill-authoring（路由摘要）
 
 > 适用范围：在 **本仓**（Flow2Spec 产品开发仓）新增或重构 `f2s-*` SKILL 时遵循。**不下发**到下游业务仓——下游不写 `f2s-*` SKILL，本主题对其无意义。

cli.js

@@ -15,6 +15,7 @@ const {
   normalizeLocale,
 } = require("./lib/flow2specConfig");
 const knowledgeEngine = require("./lib/knowledgeEngine");
+const { runDoctor, formatDoctorReport } = require("./lib/doctor");
 
 const { execFileSync } = require("child_process");
 
@@ -234,6 +235,7 @@ Flow2Spec - 统一知识库工作流（AI 配置入口）  v${pkg.version}
 用法:
   flow2spec init [agent ...] [--reset-knowledge] [--yes] [--locale zh-CN|en-US]    在当前项目初始化：写入 .Knowledge 与所选 agent 入口
   flow2spec config              打印项目根 ${CONFIG_FILENAME} 的解析结果（缺省值合并后）
+  flow2spec doctor [--json]     只读检查运行环境、项目初始化、协作上下文与知识库健康
   flow2spec kb                  知识库协作引擎：status / check / plan / apply / build
   flow2spec version             显示当前 flow2spec 版本
   flow2spec update              更新 flow2spec 到最新版本；更新后提示执行 f2s-kb-upgrade
@@ -325,6 +327,32 @@ if (sub === "config") {
   process.exit(0);
 }
 
+if (sub === "doctor") {
+  const doctorArgs = args.slice(1);
+  if (doctorArgs.includes("--help") || doctorArgs.includes("-h")) {
+    console.log(`
+用法:
+  flow2spec doctor [--json]
+
+只读检查 Node.js、项目配置、Agent 初始化、协作上下文、.task 忽略规则与知识库健康。
+警告不阻塞（exit 0），错误会返回 exit 1；本命令不会修改文件或访问网络。
+`.trim());
+    process.exit(0);
+  }
+  const unknown = doctorArgs.filter((arg) => arg !== "--json");
+  if (unknown.length > 0) {
+    console.error(`doctor 不支持参数：${unknown.join(" ")}`);
+    process.exit(1);
+  }
+  const report = runDoctor(process.cwd());
+  if (doctorArgs.includes("--json")) {
+    printJson(report);
+  } else {
+    console.log(formatDoctorReport(report));
+  }
+  process.exit(report.ok ? 0 : 1);
+}
+
 if (sub === "kb") {
   const kbSub = args[1];
   const kbFlags = new Set(args.slice(2).filter((arg) => String(arg || "").startsWith("--")));