@double-codeing/flow2spec 3.0.19 → 3.1.1

package/docs/en/directory-conventions.md

@@ -21,7 +21,7 @@ See [architecture.md §1](./architecture.md) for Memory Coding four rings.
 | `.Knowledge/topics/` | **L2** Topic summaries (hard constraints, boundaries, pointers) |
 | `.Knowledge/template/` | Templates for final drafts / technical proposals |
 | `.Knowledge/index.md` | Human-readable index |
-| `.Knowledge/manifest-routing.json` | **L0** Machine-readable routing skeleton (task/topic/`topicDependencies`) |
+| `.Knowledge/manifest-routing.json` | **L0** Machine-readable routing skeleton (task/topic/`topicDependencies`/`topicMetadata`) |
 | `.Knowledge/matchers/*.json` | **L1** Keyword fragments (`id/includeAny`); **match** reads one shard via `matcherPath` |
 | `.Knowledge/migration-report.md` | Migration comparison table and deletion path list written by `f2s-kb-migrate` |
 | `.task/` | Change tracking task directory (`active/` for in-progress, `completed/` for archived with directory name in the format **`<YYYYMMDD>-<task-name>`** (date first), `todo.json` for active task index); created only when `changeTracking.*` is `true` or `f2s-req-plan` is explicitly invoked |
@@ -38,15 +38,38 @@ See [architecture.md §1](./architecture.md) for Memory Coding four rings.
 ## Path Constraints
 
 1. `.Knowledge/topics` is the knowledge routing topic layer; it is allowed and encouraged to be maintained via `f2s-*` skills.
-2. `f2s-ctx-build` reads from `.Knowledge/stock-docs` and updates `.Knowledge/topics`, `.Knowledge/index.md`, `.Knowledge/manifest-routing.json`, `.Knowledge/matchers/*.json`.
+2. `f2s-kb-build` reads from `.Knowledge/stock-docs` and updates `.Knowledge/topics`, `.Knowledge/index.md`, `.Knowledge/manifest-routing.json`, `.Knowledge/matchers/*.json`.
 3. Implementation tasks uniformly read from `.Knowledge/req-docs/*.md`.
 4. `manifest-routing.json` and `matchers/*.json` are maintained by `f2s-*` skill workflows; `.Knowledge/manifest-matchers.json` is no longer used (`flow2spec init` will delete legacy files).
 
 ---
 
+## Topic Metadata
+
+`manifest-routing.json.topicMetadata` is machine-readable governance metadata for topics. It is only used for inventory, filtering, routing audits, upgrade gap checks, and reading expectations; it does not participate in matcher hits, does not decide whether a topic is read, is not a source of execution constraints, and must not drive `topicId` or filename changes. Execution constraints always come from explicit requirements in `AGENTS.md`, rules, skills, or topic bodies.
+
+`topicMetadata` is independent from `topicPaths`, and each key must be a topicId already present in `topicPaths`. When creating a new topic, metadata may be written if there is clear evidence; classification alone must not create, rename, or split topics.
+
+| Field | Values | Meaning |
+| --- | --- | --- |
+| `primary` | `feature` / `module` / `config` / `policy` | Single primary classification. Read the topic body and write the type that best represents its core content. |
+| `tags` | Array of `feature` / `module` / `config` / `policy` | Optional secondary classes; values must not repeat `primary`. |
+| `confidence` | `manual` / `inferred` | `manual` means human-confirmed; `inferred` means evidence-backed inference. When evidence is insufficient, do not write metadata and list it as pending confirmation in the summary. |
+
+Type meanings:
+
+| Type | Reading expectation |
+| --- | --- |
+| `feature` | Landed business or product capability background |
+| `module` | Directory, package, module boundary, and engineering structure |
+| `config` | Configuration items, switches, defaults, initialization parameters |
+| `policy` | Process, rule, constraint, gate, prohibition, agent orchestration, skill step |
+
+---
+
 ## Related Documents
 
 - [Usage Guide](./usage-guide.md)
 - [Commands Reference](./commands-reference.md)
 - [Architecture](./architecture.md)
-- [Usage Scenarios](./usage-scenarios.md)
+- [Usage Scenarios](./usage-scenarios.md)

package/docs/en/usage-guide.md

@@ -19,7 +19,7 @@ flow2spec init [cursor|claude|codex ...] --reset-knowledge
 | Aligns `manifest-routing` + `matchers/` package-level structure | Replace `f2s-*` skills for writing business semantics |
 | Overwrites `.Knowledge` template files with `--reset-knowledge` | Override existing `.Knowledge` content (without this flag) |
 
-> **`init` and "knowledge base upgrade" are two different things**: `init` only handles structural alignment — business semantics (topics content, routing terms, stock-docs/req-docs) are maintained by skills like `f2s-doc-add`, `f2s-kb-fix`, `f2s-kb-feat`, `f2s-kb-sync`, `f2s-ctx-build`, etc. For cross-version upgrades, use `f2s-kb-upgrade`. **Do not treat a standalone `init` as an upgrade command.**
+> **`init` and "knowledge base upgrade" are two different things**: `init` only handles structural alignment — business semantics (topics content, routing terms, stock-docs/req-docs) are maintained by skills like `f2s-kb-add`, `f2s-kb-fix`, `f2s-kb-feat`, `f2s-kb-sync`, `f2s-kb-build`, etc. For cross-version upgrades, use `f2s-kb-upgrade`. **Do not treat a standalone `init` as an upgrade command.**
 
 ### `f2s-*` and `flow2spec.config.json`: Multi-Client, Multi-Layered Reminders (Authority Remains the Disk JSON)
 
@@ -27,9 +27,9 @@ Before executing any **`f2s-*` skill**, the Agent needs to obtain the actual val
 
 | Client | `init` Output & Behavior | Description |
 | --- | --- | --- |
-| **Cursor** | `.cursor/rules/f2s-config-check.mdc` (`alwaysApply`) | Rule requires: **Read(`flow2spec.config.json`)** before entering skill body. |
-| **Claude Code** | `.claude/hooks/f2s-config-inject.js` + `.claude/settings.json` (PreToolUse, `Skill` matching) | Injects a config summary when invoking **`f2s-*` Skill**; when **file is missing, JSON is invalid, or hook throws an unexpected exception**, it also injects a **notice + default semantics consistent with "file not found"** to avoid silent failure; it is still recommended to **Read** for confirmation when in doubt or after config changes. |
-| **Codex** | `.codex/AGENTS.md` top-level mandatory step + `{{FLOW2SPEC_PROJECT_CONFIG}}` expansion table | **Read** is a hard requirement; the config table is a **snapshot from the last `flow2spec init`** — when it differs from disk, **Read** takes precedence. The adjacent **`.codex/topics/f2s-config-check.md`** shares its origin with the Cursor rule (including the **changeTracking** detail table); open it **as needed** — it does not need to be grouped with the three "topic long-form" examples as required reading. |
+| **Cursor** | `.cursor/rules/f2s-config-check.mdc` (`alwaysApply`) | Config reading remains rule-based: **Read(`flow2spec.config.json`)** before entering skill body. Cursor hooks are used for update checks only, not automatic config reads. |
+| **Claude Code** | `.claude/hooks/f2s-config-session.js` + `.claude/hooks/f2s-config-inject.js` + `.claude/settings.json` | `SessionStart` injects one config summary; `PreToolUse` only guards **`f2s-*` Skill** calls by reminding the agent that the first skill-body action must be **Read**. Neither replaces the disk read. |
+| **Codex** | root `AGENTS.md` mandatory step + `.codex/topics/f2s-config-check.md` + `{{FLOW2SPEC_PROJECT_CONFIG}}` expansion table | Config reading remains rule-based: **Read** is a hard requirement; the config table is a **snapshot from the last `flow2spec init`** and disk Read takes precedence. Codex hooks are used for update checks only, not automatic config reads. |
 | **Knowledge Base (optional)** | When `.Knowledge/manifest-routing` hits **`config-precheck`** | `.Knowledge/topics/f2s-config-precheck.md` is a **routing summary** that links to the Codex long-form article; Flow2Spec does **not** maintain a second full copy in `.Knowledge`, nor does it replace a `Read` of the JSON. |
 
 For field semantics and default value rules, see [Commands Reference § 6) Sub-Agent Configuration](./commands-reference.md). For the design perspective, see [Design Principles § 4.5.1](./design-principles.md).
@@ -79,20 +79,20 @@ When requirements are already clear, `f2s-req-clarify` can be skipped, starting
 ### Document Ingestion
 
 ```
-New architecture document ingestion: f2s-doc-arch → f2s-doc-final → f2s-ctx-build
-PDF/draft ingestion:               f2s-doc-final → f2s-ctx-build
+New architecture document ingestion: f2s-doc-arch → f2s-doc-final → f2s-kb-build
+PDF/draft ingestion:               f2s-doc-final → f2s-kb-build
 ```
 
-Integrate architecture descriptions or PDF final drafts into knowledge routing (generates topics/matchers/manifest-routing). To ingest a PDF into the knowledge base, use `f2s-doc-final` then `f2s-ctx-build`. `f2s-doc-pdf` only converts a PDF to Markdown under `req-docs/` for editing; it is **not** the recommended path for "PDF straight to coding."
+Integrate architecture descriptions or PDF final drafts into knowledge routing (generates topics/matchers/manifest-routing). To ingest a PDF into the knowledge base, use `f2s-doc-final` then `f2s-kb-build`. `f2s-doc-pdf` only converts a PDF to Markdown under `req-docs/` for editing; it is **not** the recommended path for "PDF straight to coding."
 
 ### Backfilling Existing Capabilities
 
 ```
-f2s-doc-add      # Aggregate multiple files, extract from source code / documents
+f2s-kb-add      # Aggregate multiple files, extract from source code / documents
 f2s-kb-sync      # Infer already-implemented capabilities from current session
 ```
 
-Use these when code has already been shipped but the knowledge base has no record. `f2s-doc-add` is suitable for batch imports; `f2s-kb-sync` is suitable for real-time consolidation at the end of a session.
+Use these when code has already been shipped but the knowledge base has no record. `f2s-kb-add` is suitable for batch imports; `f2s-kb-sync` is suitable for real-time consolidation at the end of a session.
 
 ### Routine Maintenance
 
@@ -110,6 +110,12 @@ f2s-kb-migrate (Legacy V1: old knowledge base) → f2s-kb-upgrade
 f2s-kb-upgrade (Current V2+: already has .Knowledge; includes npm v3.x projects, etc.; see skill step 0)
 ```
 
+In interactive terminals, the Flow2Spec CLI checks the latest npm version with a cache when running `flow2spec version` / `flow2spec init`. If a newer version exists, it prompts you to run `flow2spec update`, then execute `f2s-kb-upgrade` in the Agent conversation to align the project knowledge templates, manifest/matchers, and agent config roots. Failed update checks are skipped silently and do not affect the current command; checks are disabled in `CI`, non-TTY sessions, or when `FLOW2SPEC_SKIP_UPDATE_CHECK=1` is set.
+
+After `flow2spec init codex`, Codex projects include `.codex/hooks.json` and `.codex/hooks/f2s-update-check.js`. The hook runs on Codex `SessionStart` for `startup|resume` and checks the knowledge-base version automatically. When the hook is first generated or changed, trust it through `/hooks` in Codex. Set `updateCheck.enabled=false` in `flow2spec.config.json` to skip the check.
+
+After `flow2spec init cursor`, Cursor projects include `.cursor/hooks.json` and `.cursor/hooks/f2s-update-check.js`. The hook runs on Cursor `sessionStart` and injects upgrade reminders through `additional_context`. Set `updateCheck.enabled=false` in `flow2spec.config.json` to skip the check.
+
 ---
 
 ## 4. Agent Execution Configuration
@@ -154,4 +160,4 @@ Skills are triggered by matching `name` and `description`. Files are located und
 - [Commands Reference](./commands-reference.md)
 - [Directory Conventions](./directory-conventions.md)
 - [Architecture](./architecture.md)
-- [Usage Scenarios](./usage-scenarios.md)
+- [Usage Scenarios](./usage-scenarios.md)

package/docs/en/usage-scenarios.md

@@ -4,7 +4,7 @@
 
 The following examples revolve around the same e-commerce project, covering the full pipeline from requirements clarification through post-launch maintenance.
 
-**Prerequisite**: The project has executed `flow2spec init`, and `flow2spec.config.json` uses the default configuration (`subAgent: false`). `f2s-*` skills do not modify the configuration root `rules/` or `skills/` files.
+**Prerequisite**: The project has executed `flow2spec init`, and `flow2spec.config.json` uses the default configuration (`subAgent: false`; `changeTracking.feat/implement: true`, `changeTracking.fix: false`). `f2s-*` skills do not modify the configuration root `rules/` or `skills/` files.
 
 ---
 
@@ -73,7 +73,7 @@ The following examples revolve around the same e-commerce project, covering the
 
 **You**
 
-> f2s-ctx-build .Knowledge/stock-docs/order-service-architecture-final.md
+> f2s-kb-build .Knowledge/stock-docs/order-service-architecture-final.md
 
 **Agent**
 
@@ -193,4 +193,4 @@ The following examples revolve around the same e-commerce project, covering the
 - [Usage Guide](./usage-guide.md)
 - [Commands Reference](./commands-reference.md)
 - [Directory Conventions](./directory-conventions.md)
-- [Architecture](./architecture.md)
+- [Architecture](./architecture.md)

package/docs//344/275/223/347/263/273/344/270/216/345/216/237/347/220/206.md

@@ -36,7 +36,7 @@ Flow2Spec 的目标是把"业务知识沉淀"与"Agent 能力加载"拆开，并
 
 | 层级 | 路径 / 机制 | 记什么 | 典型读法 |
 | --- | --- | --- | --- |
-| **L0 路由索引** | `manifest-routing.json` | task→topic、`topicDependencies`、`topicPaths` | 会话首读（机读事实源） |
+| **L0 路由索引** | `manifest-routing.json` | task→topic、`topicDependencies`、`topicPaths`、`topicMetadata` | 会话首读（机读事实源） |
 | **L1 关键词分片** | `matchers/<id>.json` | `includeAny` 触发词 | **match**：只打开命中的一个分片 |
 | **L2 主题摘要** | `topics/<topic>.md` | 硬约束摘要、边界、下一步指针 | **expand**：拉齐依赖主题 |
 | **L3 长文档** | `stock-docs/`、`req-docs/` | 架构终稿、技术方案全文 | 按需下钻背景 |
@@ -76,7 +76,7 @@ Flow2Spec 的目标是把"业务知识沉淀"与"Agent 能力加载"拆开，并
 
 ## 5. 关键链路
 
-- 文档沉淀链：`f2s-doc-arch` → `f2s-doc-final` → `f2s-ctx-build`
+- 文档沉淀链：`f2s-doc-arch` → `f2s-doc-final` → `f2s-kb-build`
 - 实现链：`.Knowledge/req-docs/*.md` → `implement-tech-design` → 代码
 - 维护链：`f2s-kb-fix` / `f2s-kb-feat` / `f2s-kb-sync` / `f2s-kb-merge`
 - 需求规划链：`f2s-req-plan`（规划 + 实现，始终创建任务清单）
@@ -138,9 +138,9 @@ Flow2Spec 通过项目根 `flow2spec.config.json` 的 `subAgent`、`switchAgentV
 ```json
 {
   "changeTracking": {
-    "feat": false,
+    "feat": true,
     "fix": false,
-    "implement": false
+    "implement": true
   }
 }
 ```

package/docs//344/275/277/347/224/250/346/241/210/344/276/213-/346/250/241/346/213/237/345/257/271/350/257/235.md

@@ -4,7 +4,7 @@
 
 以下示例围绕同一个电商项目展开，贯穿从需求澄清到上线后维护的完整流程。
 
-**前提**：项目已执行 `flow2spec init`，`flow2spec.config.json` 使用默认配置（`subAgent: false`）。`f2s-*` 技能不改动配置根 `rules/`、`skills/` 文件。
+**前提**：项目已执行 `flow2spec init`，`flow2spec.config.json` 使用默认配置（`subAgent: false`；`changeTracking.feat/implement: true`，`changeTracking.fix: false`）。`f2s-*` 技能不改动配置根 `rules/`、`skills/` 文件。
 
 ---
 
@@ -73,7 +73,7 @@
 
 **你**
 
-> f2s-ctx-build .Knowledge/stock-docs/订单服务架构说明_终稿.md
+> f2s-kb-build .Knowledge/stock-docs/订单服务架构说明_终稿.md
 
 **Agent**
 

package/docs//344/275/277/347/224/250/350/257/264/346/230/216.md

@@ -21,7 +21,7 @@ flow2spec init [cursor|claude|codex ...] --reset-knowledge
 | `--reset-knowledge` 时强制覆盖 `.Knowledge` 模板文件 | （不加此参数时）覆盖已有 `.Knowledge` 内容 |
 
 
-> **`init` 与「知识库升级」是两件事**：`init` 只做结构补齐，业务语义（topics 内容、路由词条、stock-docs/req-docs）由 `f2s-doc-add`、`f2s-kb-fix`、`f2s-kb-feat`、`f2s-kb-sync`、`f2s-ctx-build` 等技能维护。跨版本升级用 `f2s-kb-upgrade`，**不要把单独 `init` 当作升级命令**。
+> **`init` 与「知识库升级」是两件事**：`init` 只做结构补齐，业务语义（topics 内容、路由词条、stock-docs/req-docs）由 `f2s-kb-add`、`f2s-kb-fix`、`f2s-kb-feat`、`f2s-kb-sync`、`f2s-kb-build` 等技能维护。跨版本升级用 `f2s-kb-upgrade`，**不要把单独 `init` 当作升级命令**。
 
 ### `f2s-*` 与 `flow2spec.config.json`：多端多重提示（权威仍为磁盘 JSON）
 
@@ -30,9 +30,9 @@ flow2spec init [cursor|claude|codex ...] --reset-knowledge
 
 | 端               | `init` 落盘与行为                                                                          | 说明                                                                                                                                                                                     |
 | --------------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Cursor**      | `.cursor/rules/f2s-config-check.mdc`（`alwaysApply`）                                   | 规则要求：技能正文前先 **Read(`flow2spec.config.json`)**。                                                                                                                                         |
-| **Claude Code** | `.claude/hooks/f2s-config-inject.js` + `.claude/settings.json`（PreToolUse，`Skill` 匹配） | 在调用 **`f2s-*` Skill** 时注入配置摘要；**文件缺失、JSON 无效或 hook 未预期异常**时也会注入**说明 + 与「文件不存在」一致的默认语义**，避免静默；仍建议在存疑或刚改过配置时 **Read** 核对。                                                                |
-| **Codex**       | `.codex/AGENTS.md` 顶部强制步骤 + `{{FLOW2SPEC_PROJECT_CONFIG}}` 展开表                        | **Read** 为硬要求；配置表为 **最近一次 `flow2spec init` 的快照**，与磁盘不一致时以 **Read** 为准。同目录 **`.codex/topics/f2s-config-check.md`** 与 Cursor 规则同源（含 **changeTracking** 细表），**按需**打开即可，不必与「专题长文」三条示例并列必读。 |
+| **Cursor**      | `.cursor/rules/f2s-config-check.mdc`（`alwaysApply`）                                   | 配置读取走文本约束：技能正文前先 **Read(`flow2spec.config.json`)**；Cursor hook 仅用于版本更新检测，不自动读取配置。                                                                                                  |
+| **Claude Code** | `.claude/hooks/f2s-config-session.js` + `.claude/hooks/f2s-config-inject.js` + `.claude/settings.json` | `SessionStart` 仅注入一次配置摘要；`PreToolUse` 仅在调用 **`f2s-*` Skill** 时做守门提示，提醒首步必须 **Read**。两者都不替代磁盘 Read。                                                                |
+| **Codex**       | 根 `AGENTS.md` 顶部强制步骤 + `.codex/topics/f2s-config-check.md` + `{{FLOW2SPEC_PROJECT_CONFIG}}` 展开表 | 配置读取走文本约束：**Read** 为硬要求；配置表为 **最近一次 `flow2spec init` 的快照**，与磁盘不一致时以 **Read** 为准。Codex hook 仅用于版本更新检测，不自动读取配置。 |
 | **知识库（可选）**     | `.Knowledge/manifest-routing` 命中 **`config-precheck`** 时                              | `.Knowledge/topics/f2s-config-precheck.md` 为**路由摘要**，链向 Codex 长文；**不**在 `.Knowledge` 再维护第二份全文，也**不**替代 Read JSON。                                                                      |
 
 
@@ -83,20 +83,20 @@ f2s-req-clarify 一句话需求或文档 → f2s-req-backend → 实现xx技术
 ### 文档沉淀
 
 ```
-新增架构文档沉淀：f2s-doc-arch → f2s-doc-final → f2s-ctx-build
-PDF/初稿沉淀：     f2s-doc-final → f2s-ctx-build
+新增架构文档沉淀：f2s-doc-arch → f2s-doc-final → f2s-kb-build
+PDF/初稿沉淀：     f2s-doc-final → f2s-kb-build
 ```
 
-把架构说明或 PDF 终稿纳入知识路由（生成 topics/matchers/manifest-routing）。若仅有 PDF 且要入库，先用 `f2s-doc-final` 转为终稿再 `f2s-ctx-build`；`f2s-doc-pdf` 仅把 PDF 转为 `req-docs/` 下的 Markdown 便于编辑，**不**作为「PDF 直驱编码」的推荐路径。
+把架构说明或 PDF 终稿纳入知识路由（生成 topics/matchers/manifest-routing）。若仅有 PDF 且要入库，先用 `f2s-doc-final` 转为终稿再 `f2s-kb-build`；`f2s-doc-pdf` 仅把 PDF 转为 `req-docs/` 下的 Markdown 便于编辑，**不**作为「PDF 直驱编码」的推荐路径。
 
 ### 存量能力补录
 
 ```
-f2s-doc-add      # 多文件聚合，从源码/文档提取
+f2s-kb-add      # 多文件聚合，从源码/文档提取
 f2s-kb-sync      # 从当前会话推断已实现能力
 ```
 
-代码已落地但知识库没有记录时使用。`f2s-doc-add` 适合批量导入，`f2s-kb-sync` 适合会话结束时的即时沉淀。
+代码已落地但知识库没有记录时使用。`f2s-kb-add` 适合批量导入，`f2s-kb-sync` 适合会话结束时的即时沉淀。
 
 ### 日常维护
 
@@ -114,6 +114,12 @@ f2s-kb-migrate（流程 V1：旧库）→ f2s-kb-upgrade
 f2s-kb-upgrade（流程现行库 V2+：已有 .Knowledge；含 npm v3.x 等，见技能步骤 0）
 ```
 
+Flow2Spec CLI 在交互式执行 `flow2spec version` / `flow2spec init` 时会按缓存检查 npm 最新版本；若发现新版本，会提示先执行 `flow2spec update`，随后在 Agent 对话中执行 `f2s-kb-upgrade`，用于对齐项目知识库模板、manifest/matchers 与配置根产物。更新检查失败会静默跳过，不影响当前命令；`CI`、非 TTY 或设置 `FLOW2SPEC_SKIP_UPDATE_CHECK=1` 时不检查。
+
+Codex 项目执行 `flow2spec init codex` 后会写入 `.codex/hooks.json` 与 `.codex/hooks/f2s-update-check.js`，在 Codex `SessionStart` 的 `startup|resume` 事件自动检查知识库版本；首次生成或 hook 内容变化后，需要在 Codex 中通过 `/hooks` 信任该项目 hook。`flow2spec.config.json` 中 `updateCheck.enabled=false` 时跳过检查。
+
+Cursor 项目执行 `flow2spec init cursor` 后会写入 `.cursor/hooks.json` 与 `.cursor/hooks/f2s-update-check.js`，在 Cursor `sessionStart` 自动检查知识库版本；脚本通过 `additional_context` 把升级提示注入会话。`flow2spec.config.json` 中 `updateCheck.enabled=false` 时跳过检查。
+
 ---
 
 ## 四、Agent 执行配置
@@ -159,4 +165,3 @@ f2s-kb-upgrade（流程现行库 V2+：已有 .Knowledge；含 npm v3.x 等，
 - [目录与路径约定](./目录与路径约定.md)
 - [体系与原理](./体系与原理.md)
 - [使用案例-模拟对话](./使用案例-模拟对话.md)
-

package/docs//345/221/275/344/273/244/350/257/264/346/230/216.md

@@ -8,14 +8,14 @@
 |---|---|---|
 | `/f2s-doc-arch` | 扫描项目，生成架构说明初稿 | 文档沉淀 |
 | `/f2s-doc-final` | PDF / 初稿转《终稿模版》规范格式 | 文档沉淀 |
-| `/f2s-ctx-build` | 终稿文档同步到知识库路由（生成 topics / matchers / manifest） | 文档沉淀 |
-| `/f2s-doc-add <路径>` | 已落地能力多文件聚合入知识库 | 文档沉淀 |
-| `/f2s-ctx-rm` | 删除某 stock-docs 文档对应的知识主题与索引映射 | 文档沉淀 |
+| `/f2s-kb-build` | 终稿文档同步到知识库路由（生成 topics / matchers / manifest） | 文档沉淀 |
+| `/f2s-kb-add <路径>` | 已落地能力多文件聚合入知识库 | 文档沉淀 |
+| `/f2s-kb-rm` | 删除某 stock-docs 文档对应的知识主题与索引映射 | 文档沉淀 |
 | `/f2s-doc-pdf` | PDF 技术方案转 Markdown，保存到 req-docs | 文档沉淀 |
 | `/f2s-req-clarify` | 需求澄清，多轮问答明确需求边界 | 需求与方案 |
 | `/f2s-req-backend` | 基于澄清结果生成后端技术方案文档 | 需求与方案 |
 | `/f2s-req-plan` | 按技术方案拆任务清单，支持并行实现 （不依赖 `changeTracking.*` 配置） | 需求与方案 |
-| `/f2s-git-commit` | 提交代码，自动检查知识库覆盖情况 | 提交 |
+| `/f2s-git-commit` | 提交代码，默认检查知识库覆盖；说“快捷提交”时跳过覆盖检查 | 提交 |
 | `/f2s-kb-feat` | 新增能力，补全实现 + 同步知识库 | 知识库维护 |
 | `/f2s-kb-fix` | 修复 BUG + 自动同步知识库 | 知识库维护 |
 | `/f2s-kb-sync` | 将会话中已实现能力沉淀回知识库 | 知识库维护 |
@@ -42,7 +42,7 @@
 **关联关系**：
 
 - **前置**：无
-- **后续**：`f2s-doc-final`（规范化终稿）→ `f2s-ctx-build`（**须终稿入参**；初稿不可直驱 build）
+- **后续**：`f2s-doc-final`（规范化终稿）→ `f2s-kb-build`（**须终稿入参**；初稿不可直驱 build）
 - **输出**：`.Knowledge/stock-docs/<架构说明>_初稿.md`
 
 **子 agent 调用**：
@@ -65,7 +65,7 @@
 
 **作用**：将 PDF 技术方案或初稿文档转为《终稿模版》规范格式，统一文档结构，便于后续进入知识库。
 
-**工作原理**：将非结构化或格式各异的文档（PDF/初稿）对照内置终稿模版进行格式归一化：提取核心概念表、业务规则、关键流程、配置与错误处理等标准章节，补齐缺失段落标记，最终输出格式统一的 `_终稿.md`。终稿是 `f2s-ctx-build` 的标准输入物，确保知识库入口的结构一致性。
+**工作原理**：将非结构化或格式各异的文档（PDF/初稿）对照内置终稿模版进行格式归一化：提取核心概念表、业务规则、关键流程、配置与错误处理等标准章节，补齐缺失段落标记，最终输出格式统一的 `_终稿.md`。终稿是 `f2s-kb-build` 的标准输入物，确保知识库入口的结构一致性。
 
 **使用场景**：
 
@@ -76,7 +76,7 @@
 **关联关系**：
 
 - **前置**：PDF 文档或初稿文档
-- **后续**：`f2s-ctx-build`（终稿入库）
+- **后续**：`f2s-kb-build`（终稿入库）
 - **输出**：`.Knowledge/stock-docs/<文档>_终稿.md`
 
 **子 agent 调用**：
@@ -95,7 +95,7 @@
 
 ---
 
-### `f2s-ctx-build`
+### `f2s-kb-build`
 
 **作用**：将 `stock-docs/` 中的沉淀文档（架构、终稿）同步到知识库路由系统，生成/更新主题文件、索引、manifest-routing、matchers。
 
@@ -135,11 +135,11 @@
 
 ---
 
-### `f2s-doc-add`
+### `f2s-kb-add`
 
 **作用**：将已落地能力（多文件聚合）解析进知识库。适用于代码已实现但缺少文档，或已有多个文档需要统一入库的场景。
 
-**工作原理**：从多个分散的源文件（代码、配置、散落文档）中聚合提取能力描述，走完整的「初稿→终稿→topics/index/manifest」沉淀链路。与 `f2s-ctx-build` 的区别在于输入：`ctx-build` 从已有的单份终稿驱动，`doc-add` 从多个散落源聚合后再走同一管线。本质是补齐「有实现无文档」的缺口。
+**工作原理**：从多个分散的源文件（代码、配置、散落文档）中聚合提取能力描述，走完整的「初稿→终稿→topics/index/manifest」沉淀链路。与 `f2s-kb-build` 的区别在于输入：`ctx-build` 从已有的单份终稿驱动，`doc-add` 从多个散落源聚合后再走同一管线。本质是补齐「有实现无文档」的缺口。
 
 **使用场景**：
 
@@ -175,11 +175,11 @@
 
 ---
 
-### `f2s-ctx-rm`
+### `f2s-kb-rm`
 
 **作用**：按 stock-docs 文档删除对应的知识主题与索引映射。仅删除知识库中的引用关系，不删除源文档本身。
 
-**工作原理**：`f2s-ctx-build` 的逆操作——给定一份 `stock-docs` 文档路径，定位其在 `manifest-routing.json` 中的 task→topic 规则、对应的 `matchers/<id>.json` 分片、`topics/<topic>.md` 文件以及 `index.md` 中的行项，逐一清除引用。若删除后某 topic 无任何 task 引用，则移除该 topic 文件。源文档本身保留不动，用户可自行决定是否物理删除。
+**工作原理**：`f2s-kb-build` 的逆操作——给定一份 `stock-docs` 文档路径，定位其在 `manifest-routing.json` 中的 task→topic 规则、对应的 `matchers/<id>.json` 分片、`topics/<topic>.md` 文件以及 `index.md` 中的行项，逐一清除引用。若删除后某 topic 无任何 task 引用，则移除该 topic 文件。源文档本身保留不动，用户可自行决定是否物理删除。
 
 **使用场景**：
 
@@ -216,7 +216,7 @@
 
 - **前置**：PDF 文档
 - **输出**：`.Knowledge/req-docs/<方案>.md`
-- **下一步**（推荐）：`f2s-req-clarify` → `f2s-req-backend` → 按 `req-docs/` 中技术方案 MD 触发 `implement-tech-design`；若目标是知识库沉淀则 `f2s-doc-final` → `f2s-ctx-build`
+- **下一步**（推荐）：`f2s-req-clarify` → `f2s-req-backend` → 按 `req-docs/` 中技术方案 MD 触发 `implement-tech-design`；若目标是知识库沉淀则 `f2s-doc-final` → `f2s-kb-build`
 
 **子 agent 调用**：
 
@@ -337,14 +337,15 @@
 
 ### `f2s-git-commit`
 
-**作用**：代码写完后执行 Git 提交。自动检查变更文件、比对知识库覆盖情况，未入库的能力会提示用户处理，确认提交信息后执行 commit。
+**作用**：代码写完后执行 Git 提交。默认自动检查变更文件、比对知识库覆盖情况，未入库的能力会提示用户处理；用户明确说“快捷提交”时跳过知识库覆盖检查。提交前会展示提交信息首行，然后直接执行 commit。
 
-**工作原理**：在 `git commit` 之上叠加「知识库覆盖门控」——先通过 `git diff` 推断本次变更涉及的功能模块，再与 `.Knowledge/topics/` 和 `stock-docs/` 交叉比对，判断变更能力是否已有知识库记录。未覆盖时阻断并提示三选（补录/跳过/取消），避免「代码有了但知识库不知道」的静默漂移。提交信息强制 emoji + Conventional Commits 格式，保证 git log 的机读一致性。
+**工作原理**：在 `git commit` 之上叠加「知识库覆盖门控」——先通过 `git diff` 推断本次变更涉及的功能模块，再与 `.Knowledge/topics/` 和 `stock-docs/` 交叉比对，判断变更能力是否已有知识库记录。未覆盖时阻断并提示三选（补录/跳过/取消），避免「代码有了但知识库不知道」的静默漂移。快捷提交模式只跳过这层覆盖门控，不跳过冲突检查、提交信息展示、精确 `git add`、git hooks。提交信息强制 emoji + Conventional Commits 格式，保证 git log 的机读一致性。
 
 **使用场景**：
 
 - 每次功能实现或 Bug 修复后提交代码
 - 希望在提交时得到知识库覆盖情况的提醒
+- 已明确不需要本次覆盖检查，只想快捷提交
 - 需要 AI 帮助生成有意义的提交信息
 
 **关联关系**：
@@ -356,7 +357,7 @@
 **执行流程**：
 
 1. `git status --short` + `git diff HEAD` 区分 staged / unstaged / untracked 三类文件；发现 merge conflict 标记立即终止
-2. 对比 `.Knowledge/topics/` 与 `stock-docs/`，判断本次变更能力是否已入库；`.Knowledge` 不存在时跳过并提示
+2. 默认对比 `.Knowledge/topics/` 与 `stock-docs/`，判断本次变更能力是否已入库；`.Knowledge` 不存在时跳过并提示；用户说“快捷提交”时跳过本步
 3. 未覆盖时提示用户选择：A) 先补录再提交 / B) 先提交稍后补录 / C) 取消
 4. 基于 `git diff` 实际内容生成提交信息草稿，等待用户确认或修改
 5. `git add <具体文件>` + `git commit`；hook 失败则提示修复，不跳过
@@ -367,7 +368,7 @@
 - 禁止 `git add -A` / `git add .`，只 add 已确认的变更文件
 - 禁止 `--no-verify`，hook 失败须修复后重试
 - 禁止自动 push
-- 提交信息必须经用户确认，不可静默提交
+- 提交前必须展示提交信息首行；不要求用户额外确认 commit
 
 **子 agent 调用**：无（全程交互确认，主 agent 内完成）
 
@@ -474,7 +475,7 @@
 - **前置**：无（可直接触发，或零输入推断）
 - **后续**：无
 - **特点**：先输出知识库更新大纲，用户确认后才写入
-- **与 `f2s-ctx-build` 区别**：`ctx-build` 从 `stock-docs` 驱动，`kb-sync` 从会话/代码推断
+- **与 `f2s-kb-build` 区别**：`ctx-build` 从 `stock-docs` 驱动，`kb-sync` 从会话/代码推断
 
 **子 agent 调用**：
 
@@ -585,6 +586,9 @@
 
 - flow2spec 包版本升级后，升级项目知识库模板
 - 旧项目升级到最新结构
+- CLI 在交互式 `flow2spec version` / `flow2spec init` 中发现 npm 有新版本后，会提示先 `flow2spec update`，再在 Agent 对话中执行本技能
+- Cursor 通过 `.cursor/hooks.json` 在 `sessionStart` 自动检测到知识库版本落后后，会提示执行本技能
+- Codex 通过 `.codex/hooks.json` 在 `SessionStart` 自动检测到知识库版本落后后，会提示执行本技能（首次或变更后需在 Codex `/hooks` 中信任）
 
 **关联关系**：
 
@@ -619,14 +623,8 @@
 
 以下不是技能命令，而是通过触发词激活的规则，用于辅助指导 Agent 的行为。
 
-### `f2s-karpathy-guidelines`
-
-**触发词**：`alwaysApply`（始终生效，无需显式触发）
-
-**作用**：Flow2Spec 内置的 Karpathy 式编码行为准则，约束 Agent 的编码决策质量。
-
-**工作原理**：从 Andrej Karpathy 对 LLM 写代码常见失误的观察中提炼四条行为约束，作为 `alwaysApply` 规则在所有 `f2s-*` 技能执行时隐式生效：① 先想清楚再写代码（假设要说清楚，不确定就问）；② 简单优先（用最少代码解决问题）；③ 手术式修改（只动该动的，风格对齐现有代码）；④ 目标驱动执行（先定义可验证的成功标准再循环迭代）。当这些准则与 `f2s-*` 强制步骤冲突时，以 `f2s-*` 为准。
 
+---
 ---
 
 ### `f2s-task`
@@ -653,28 +651,8 @@
 
 ---
 
-### `stock-docs-vs-req-docs`
-
-**触发词**：stock-docs、req-docs、已落地能力、技术方案放哪、PDF 终稿
-
-**作用**：区分知识沉淀目录与需求实现目录的边界。
-
-**工作原理**：通过「用途隔离」避免文档混放——`stock-docs/` 存放已沉淀的存量知识（架构、终稿），由 `ctx-build` 消费入库，禁止直接用于编码；`req-docs/` 存放面向实现的需求与技术方案，由 `implement-tech-design` 规则消费驱动编码。两目录的写入者和消费者完全隔离，防止「存量描述被当编码依据」或「实现方案被当能力沉淀」的混淆。
-
-**目录分工**：
-
-
-| 目录            | 用途            | 写入时机                                           |
-| ------------- | ------------- | ---------------------------------------------- |
-| `stock-docs/` | 存量沉淀（架构、终稿）   | `f2s-doc-arch`、`f2s-doc-final`、`f2s-ctx-build` |
-| `req-docs/`   | 需求与技术方案（驱动实现） | `f2s-req-backend`、`f2s-doc-pdf`、手动放置           |
-
-
-**使用场景**：
-
-- 不确定文档应该放哪里
-- 需要明确 stock-docs 与 req-docs 的分工
 
+---
 ---
 
 ### `implement-tech-design`
@@ -715,11 +693,11 @@
 
 ## 6) 子 Agent 配置说明
 
-通过项目根 `flow2spec.config.json` 控制（字段默认均为 `false`）。
+通过项目根 `flow2spec.config.json` 控制。默认值：`subAgent=false`、`switchAgentVerification=false`、`changeTracking.feat=true`、`changeTracking.fix=false`、`changeTracking.implement=true`。
 
 ### 多端如何「看到」配置（与下文字段表配合）
 
-`subAgent` 等写在 **磁盘 JSON**；各产品不保证自动打开文件，故用 **Cursor 规则 / Claude hook / Codex AGENTS 快照表 / 知识库 `config-precheck` 摘要** 多层提示，**权威仍为 Read(`flow2spec.config.json`)**（设计意图见 [设计说明 § 四、5.1](./设计说明.md)，演讲口径见 [Flow2Spec-演讲稿 Slide 13b](./Flow2Spec-演讲稿.md)）。**完整路径与表格只维护一处**：[使用说明 § 一、`f2s-`* 与 `flow2spec.config.json](./使用说明.md)`。
+`subAgent` 等写在 **磁盘 JSON**；各产品不保证自动打开文件，故用 **Cursor 规则 / Claude SessionStart 摘要 + PreToolUse 守门 / Codex AGENTS 快照表 / 知识库 `config-precheck` 摘要** 多层提示，**权威仍为 Read(`flow2spec.config.json`)**（设计意图见 [设计说明 § 四、5.1](./设计说明.md)，演讲口径见 [Flow2Spec-演讲稿 Slide 13b](./Flow2Spec-演讲稿.md)）。**完整路径与表格只维护一处**：[使用说明 § 一、`f2s-`* 与 `flow2spec.config.json](./使用说明.md)`。
 
 ### `subAgent` 字段
 
@@ -746,9 +724,9 @@
 ```json
 {
   "changeTracking": {
-    "feat": false,
+    "feat": true,
     "fix": false,
-    "implement": false
+    "implement": true
   }
 }
 ```
@@ -781,4 +759,3 @@
 - [目录与路径约定](./目录与路径约定.md)
 - [体系与原理](./体系与原理.md)
 - [使用案例-模拟对话](./使用案例-模拟对话.md)
-

package/docs//347/233/256/345/275/225/344/270/216/350/267/257/345/276/204/347/272/246/345/256/232.md

@@ -21,7 +21,7 @@ Memory Coding 四环总览见 [体系与原理 §1](./体系与原理.md)。
 | `.Knowledge/topics/` | **L2** 主题摘要（硬约束、边界、路由指针） |
 | `.Knowledge/template/` | 终稿/技术方案模板 |
 | `.Knowledge/index.md` | 人类可读索引 |
-| `.Knowledge/manifest-routing.json` | **L0** 机读路由骨架（task/topic/`topicDependencies`） |
+| `.Knowledge/manifest-routing.json` | **L0** 机读路由骨架（task/topic/`topicDependencies`/`topicMetadata`） |
 | `.Knowledge/matchers/*.json` | **L1** 关键词分片（`id/includeAny`），由 `matcherPath` 直链；**match** 只读一片 |
 | `.Knowledge/migration-report.md` | `f2s-kb-migrate` 落盘的迁移对照表与拟删除路径列表 |
 | `.task/` | 变更追踪任务清单目录（`active/` 进行中，`completed/` 已归档且目录名为 **`<YYYYMMDD>-<task-name>`**（日期在前），`todo.json` 活跃任务索引）；仅当 `changeTracking.*` 为 `true` 或显式调用 `f2s-req-plan` 时创建 |
@@ -38,15 +38,38 @@ Memory Coding 四环总览见 [体系与原理 §1](./体系与原理.md)。
 ## 路径约束
 
 1. `.Knowledge/topics` 是知识路由主题层，允许并鼓励通过 `f2s-*` 技能维护。
-2. `f2s-ctx-build` 从 `.Knowledge/stock-docs` 读，更新 `.Knowledge/topics`、`.Knowledge/index.md`、`.Knowledge/manifest-routing.json`、`.Knowledge/matchers/*.json`。
+2. `f2s-kb-build` 从 `.Knowledge/stock-docs` 读，更新 `.Knowledge/topics`、`.Knowledge/index.md`、`.Knowledge/manifest-routing.json`、`.Knowledge/matchers/*.json`。
 3. 实现类任务统一读取 `.Knowledge/req-docs/*.md`。
 4. `manifest-routing.json` 与 `matchers/*.json` 由 `f2s-*` 技能流程维护；不再使用 `.Knowledge/manifest-matchers.json`（`flow2spec init` 会删除遗留文件）。
 
 ---
 
+## 主题元数据
+
+`manifest-routing.json.topicMetadata` 是 topic 的机读治理元数据，只用于盘点、过滤、路由审计、升级补缺和阅读预期；不参与 matcher 命中，不决定是否读取 topic，不作为执行强制性的事实源，也不驱动 `topicId` 或文件名变化。执行强制性始终以 `AGENTS.md`、rules、skills 与 topic 正文中的明确要求为准。
+
+`topicMetadata` 独立于 `topicPaths`，key 必须是 `topicPaths` 中已存在的 topicId。新增 topic 时有明确证据可同步写入；仅补分类不得创建 topic、重命名 topic 或拆分 topic。
+
+| 字段 | 取值 | 说明 |
+| --- | --- | --- |
+| `primary` | `feature` / `module` / `config` / `policy` | 单值主分类。取 topic 最核心的性质，读 topic 正文后写入。 |
+| `tags` | `feature` / `module` / `config` / `policy` 数组 | 可选次要分类，不得与 `primary` 重复。 |
+| `confidence` | `manual` / `inferred` | `manual` 为人工确认；`inferred` 为有明确证据推断；证据不足时不写 metadata，并在摘要列为待确认。 |
+
+类型含义：
+
+| 类型 | 阅读预期 |
+| --- | --- |
+| `feature` | 已落地业务/产品能力背景 |
+| `module` | 目录、包、模块边界与工程结构 |
+| `config` | 配置项、开关、默认值、初始化参数 |
+| `policy` | 流程、规则、约束、门禁、禁止项、agent 编排、技能步骤 |
+
+---
+
 ## 相关文档
 
 - [使用说明](./使用说明.md)
 - [命令说明](./命令说明.md)
 - [体系与原理](./体系与原理.md)
-- [使用案例-模拟对话](./使用案例-模拟对话.md)
+- [使用案例-模拟对话](./使用案例-模拟对话.md)