@double-codeing/flow2spec 3.0.18 → 3.1.0

package/README.en.md

@@ -50,10 +50,10 @@ AI: Starting implementation, 3 files affected.
 
 ---
 
-## What Flow2Spec Does (3 Things)
+## What Flow2Spec Does
 
-**① Remembers project context across devices and sessions**  
-`.Knowledge/` structured knowledge base: routing manifest (`manifest-routing.json`) + keyword indices (matchers) + topic shards (topics). AI only loads what's relevant.
+**① Remembers project context across sessions**  
+`.Knowledge/` structured knowledge base: routing manifest (`manifest-routing.json`) + keyword indices (matchers) + topic shards (topics). AI only loads what's relevant — 4.7 MB of source code compressed to ~300 lines of precise context.
 
 **② Routing manifest means AI doesn't dig through your repo**  
 Each task hits 1–4 topics, ~300 lines. Business constraints — Redis lock keys, error codes, batch limits — are all in the topics. AI doesn't have to guess from source code.
@@ -61,6 +61,15 @@ Each task hits 1–4 topics, ~300 lines. Business constraints — Redis lock key
 **③ f2s-* skills update knowledge as you code**  
 `/f2s-kb-feat` writes topics while writing features, `/f2s-kb-fix` corrects topics while fixing bugs, `/f2s-git-commit` checks topic coverage before committing. Changing code == updating knowledge. No separate "documentation maintenance."
 
+**④ Full pipeline from requirements to code**  
+`/f2s-req-clarify` asks questions until requirements are unambiguous. `/f2s-req-backend` generates a ready-to-implement technical proposal into `req-docs/`. AI implements from the proposal — no relying on verbal agreements.
+
+**⑤ Task checklists track progress across sessions**  
+When `changeTracking` is enabled, skills like `f2s-kb-feat` / `f2s-kb-fix` automatically create a `task.md` with checkboxes. Each step is checked off immediately to disk. New sessions auto-load the remaining checklist — no relying on memory. User-side todos (run SQL, set env vars, click approvals) go into `user-todos.md`, separate from AI steps.
+
+**⑥ Document-driven: PDF / MD straight into the knowledge base**  
+`/f2s-kb-add` aggregates source files into draft → final → topics. `/f2s-doc-final` converts any PDF or MD into the canonical final-draft format. External docs and legacy proposals all become routable knowledge.
+
 ---
 
 ## Getting Started
@@ -103,7 +112,7 @@ In your Agent tool (Cursor / Claude Code):
 
 > This step is done once. You won't need to repeat it for daily development.
 
-2. `/f2s-doc-add <folder path>` — Import any feature modules that haven't been added yet
+2. `/f2s-kb-add <folder path>` — Import any feature modules that haven't been added yet
 
 > Do this selectively before starting development when you notice a module's knowledge is missing from the knowledge base.
 
@@ -116,7 +125,7 @@ In your Agent tool (Cursor / Claude Code):
 ```
 /f2s-req-clarify  one-line description or paste PRD    ← clarify requirements
 /f2s-req-backend                                       ← generate technical proposal
-natural language: implement the proposal above         ← AI starts coding
+natural language: implement the proposal above         ← AI starts coding (task checklist auto-created when changeTracking is on)
 (debug and verify)
 /f2s-kb-feat  add xxx capability                       ← if something's missing
 /f2s-kb-fix   fix xxx                                  ← if there's a bug
@@ -143,7 +152,7 @@ natural language: implement the proposal above         ← AI starts coding
 | `/f2s-kb-fix` | Fix a bug |
 | `/f2s-kb-sync` | Sync knowledge base |
 | `/f2s-git-commit` | Commit code |
-| `/f2s-doc-add <path>` | Import API module into knowledge base |
+| `/f2s-kb-add <path>` | Import API module into knowledge base |
 
 For the full command list, see [Usage Guide](./docs/en/usage-guide.md) · [Commands Reference](./docs/en/commands-reference.md)
 

package/README.md

@@ -48,19 +48,25 @@ AI: 开始改，预计 3 处文件。
 
 ---
 
-## Flow2Spec 做三件事
+## Flow2Spec 做这些事
 
-**① 跨设备会话记住项目上下文**  
-`.Knowledge/` 结构化知识库：路由清单（manifest-routing.json）+ 关键词索引（matchers）+ 主题分片（topics）。AI
-启动时只读该读的。
+**① 跨会话记住项目上下文**  
+`.Knowledge/` 结构化知识库：路由清单（manifest-routing.json）+ 关键词索引（matchers）+ 主题分片（topics）。AI 启动时只读该读的，4.7 MB 源码压到 300 行精准上下文。
 
 **② 路由清单让 AI 不翻仓库，只拿该拿的**  
-每次需求命中 1~4 个 topic，约 300 行。业务的硬约束——锁的 key、错误码、上限——都在
-topic 里，AI 不用从源码猜。
+每次需求命中 1~4 个 topic，约 300 行。业务的硬约束——锁的 key、错误码、上限——都在 topic 里，AI 不用从源码猜。
 
 **③ f2s-* 技能改代码顺手更新知识**  
-`/f2s-kb-feat` 写功能时同步写 topic，`/f2s-kb-fix` 修 bug 时更正 topic，
-`/f2s-git-commit` 提交前检查 topic 覆盖。改代码就是记知识，没有"单独维护文档"这件事。
+`/f2s-kb-feat` 写功能时同步写 topic，`/f2s-kb-fix` 修 bug 时更正 topic，`/f2s-git-commit` 提交前检查 topic 覆盖。改代码就是记知识，没有"单独维护文档"这件事。
+
+**④ 需求到实现全链路：澄清 → 技术方案 → 代码**  
+`/f2s-req-clarify` 反问到无歧义，`/f2s-req-backend` 生成可直接实现的技术方案文档落到 `req-docs/`，AI 按方案实现，不靠口头约定。
+
+**⑤ 任务清单跨会话追踪进度**  
+开启 `changeTracking` 配置后，`f2s-kb-feat` / `f2s-kb-fix` 等技能执行时自动创建带 checkbox 的 `task.md`，每步完成立即打钩落盘。新会话续作时自动加载剩余清单，不靠记忆、不靠口头，任务进度永远在磁盘上。用户侧的代办（执行 SQL、配环境变量、点审批）单独写入 `user-todos.md`，不混在 AI 步骤里。
+
+**⑥ 文档驱动：PDF / MD 一键入知识库**  
+`/f2s-kb-add` 把已落地能力的源码聚合成初稿 → 终稿 → topics，`/f2s-doc-final` 把 PDF 或任意 MD 转成规范终稿格式。外部文档、历史方案都能变成可路由的知识。
 
 ---
 
@@ -104,7 +110,7 @@ npx @double-codeing/flow2spec@latest init
 
 > 这一步只做一次，之后日常开发不需要重复。
 
-2. `/f2s-doc-add <文件夹路径>` — 把还没入库的功能模块路径补进来
+2. `/f2s-kb-add <文件夹路径>` — 把还没入库的功能模块路径补进来
 
 > 这一步在进入开发前，发现没有某个模块能力的知识的时候选择性的去做
 
@@ -117,7 +123,7 @@ npx @double-codeing/flow2spec@latest init
 ```
 /f2s-req-clarify  一句话需求或粘贴 PRD    ← 需求澄清
 /f2s-req-backend                          ← 生成技术方案
-自然语言：实现上面的技术方案              ← AI 开始实现
+自然语言：实现上面的技术方案              ← AI 开始实现（开启 changeTracking 时自动建任务清单）
 （调试验证）
 /f2s-kb-feat  新增 xxx 能力               ← 功能缺失时补能力
 /f2s-kb-fix   修复 xxx                    ← 有 BUG 时修复
@@ -144,7 +150,7 @@ npx @double-codeing/flow2spec@latest init
 | `/f2s-kb-fix` | 改 BUG |
 | `/f2s-kb-sync` | 同步知识库 |
 | `/f2s-git-commit` | 提交代码 |
-| `/f2s-doc-add <路径>` | 接口模块入知识库 |
+| `/f2s-kb-add <路径>` | 接口模块入知识库 |
 
 更多命令详见 [使用说明](./docs/使用说明.md) · [命令说明](./docs/命令说明.md)
 

package/docs/.mermaid-cache.json

@@ -21,7 +21,7 @@
       "marker": "MERMAID_a24148e2b009"
     },
     {
-      "content": "graph LR\n    K[\".Knowledge/\"] --> AI[\"下次会话\\n的 AI\"]\n    AI --> C[\"功能迭代\"]\n\n    C -->|\"修复 Bug\"| FIX[\"f2s-kb-fix\"] --> K\n    C -->|\"新增能力\"| FEAT[\"f2s-kb-feat\"] --> K\n    C -->|\"会话结束\"| SYNC[\"f2s-kb-sync\"] --> K\n    C -->|\"提交代码\"| CMT[\"f2s-git-commit\\n收口检查\"]\n    CMT -->|\"未入库则提醒\\n-> kb-sync/kb-feat\"| K\n\n    D1[\"架构文档\"] -->|f2s-doc-arch| FIN[\"f2s-doc-final\"]\n    D2[\"PDF/初稿\"] -->|f2s-doc-final| FIN\n    FIN --> CTX[\"f2s-ctx-build\"] --> K\n\n    OLD[\"存量代码/文档\"] -->|f2s-doc-add| K\n\n    NR[\"新需求\"] --> CL[\"f2s-req-clarify\"] --> BE[\"f2s-req-backend\"]\n    BE --> IMPL[\"实现xxx技术方案\"] -->|自动触发implement-tech-design规则| K\n\n    GIT[\"Git 合并后\"] -->|f2s-kb-merge| K",
+      "content": "graph LR\n    K[\".Knowledge/\"] --> AI[\"下次会话\\n的 AI\"]\n    AI --> C[\"功能迭代\"]\n\n    C -->|\"修复 Bug\"| FIX[\"f2s-kb-fix\"] --> K\n    C -->|\"新增能力\"| FEAT[\"f2s-kb-feat\"] --> K\n    C -->|\"会话结束\"| SYNC[\"f2s-kb-sync\"] --> K\n    C -->|\"提交代码\"| CMT[\"f2s-git-commit\\n收口检查\"]\n    CMT -->|\"未入库则提醒\\n-> kb-sync/kb-feat\"| K\n\n    D1[\"架构文档\"] -->|f2s-doc-arch| FIN[\"f2s-doc-final\"]\n    D2[\"PDF/初稿\"] -->|f2s-doc-final| FIN\n    FIN --> CTX[\"f2s-kb-build\"] --> K\n\n    OLD[\"存量代码/文档\"] -->|f2s-kb-add| K\n\n    NR[\"新需求\"] --> CL[\"f2s-req-clarify\"] --> BE[\"f2s-req-backend\"]\n    BE --> IMPL[\"实现xxx技术方案\"] -->|自动触发implement-tech-design规则| K\n\n    GIT[\"Git 合并后\"] -->|f2s-kb-merge| K",
       "hash": "6335fa6eda40",
       "marker": "MERMAID_6335fa6eda40"
     },

package/docs/en/architecture.md

@@ -34,7 +34,7 @@ Four rings in the repo (do not collapse rules + skills into a single "third ring
 
 | Layer | Path / mechanism | Stores | Typical read |
 | --- | --- | --- | --- |
-| **L0 routing** | `manifest-routing.json` | task→topic, `topicDependencies`, `topicPaths` | First read (machine source of truth) |
+| **L0 routing** | `manifest-routing.json` | task→topic, `topicDependencies`, `topicPaths`, `topicMetadata` | First read (machine source of truth) |
 | **L1 matcher shard** | `matchers/<id>.json` | `includeAny` triggers | **match**: one shard only |
 | **L2 topic summary** | `topics/<topic>.md` | Hard constraints, boundaries, pointers | **expand**: pull dependency topics |
 | **L3 long docs** | `stock-docs/`, `req-docs/` | Architecture finals, tech specs | Drill down on demand |
@@ -74,7 +74,7 @@ Codex does not read the `rules/` directory; execution constraints are carried th
 
 ## 5. Key Chains
 
-- Documentation curation chain: `f2s-doc-arch` -> `f2s-doc-final` -> `f2s-ctx-build`
+- Documentation curation chain: `f2s-doc-arch` -> `f2s-doc-final` -> `f2s-kb-build`
 - Implementation chain: `.Knowledge/req-docs/*.md` -> `implement-tech-design` -> code
 - Maintenance chain: `f2s-kb-fix` / `f2s-kb-feat` / `f2s-kb-sync` / `f2s-kb-merge`
 - Requirements planning chain: `f2s-req-plan` (planning + implementation, always creates task checklist)
@@ -165,4 +165,4 @@ Design intent: Cross-verification introduces an external perspective, reducing t
 - [Usage Guide](./usage-guide.md)
 - [Commands Reference](./commands-reference.md)
 - [Directory Conventions](./directory-conventions.md)
-- [Usage Scenarios](./usage-scenarios.md)
+- [Usage Scenarios](./usage-scenarios.md)

package/docs/en/commands-reference.md

@@ -8,9 +8,9 @@
 |---|---|---|
 | `/f2s-doc-arch` | Scan project, generate architecture draft | Doc Curation |
 | `/f2s-doc-final` | Convert PDF / draft to standardized final-draft format | Doc Curation |
-| `/f2s-ctx-build` | Sync final drafts into knowledge base routing (topics / matchers / manifest) | Doc Curation |
-| `/f2s-doc-add <path>` | Aggregate multi-file implemented capabilities into knowledge base | Doc Curation |
-| `/f2s-ctx-rm` | Remove knowledge topic and index mapping for a stock-docs document | Doc Curation |
+| `/f2s-kb-build` | Sync final drafts into knowledge base routing (topics / matchers / manifest) | Doc Curation |
+| `/f2s-kb-add <path>` | Aggregate multi-file implemented capabilities into knowledge base | Doc Curation |
+| `/f2s-kb-rm` | Remove knowledge topic and index mapping for a stock-docs document | Doc Curation |
 | `/f2s-doc-pdf` | Convert PDF technical proposal to Markdown, save to req-docs | Doc Curation |
 | `/f2s-req-clarify` | Clarify requirements via multi-round Q&A | Requirements |
 | `/f2s-req-backend` | Generate backend technical proposal from clarified requirements | Requirements |
@@ -40,7 +40,7 @@
 
 **Relationships**:
 - **Prerequisite**: None
-- **Next Step**: `f2s-doc-final` (normalized final draft) → `f2s-ctx-build` (**final draft input only**; do not run build on `_draft` / `_初稿` files)
+- **Next Step**: `f2s-doc-final` (normalized final draft) → `f2s-kb-build` (**final draft input only**; do not run build on `_draft` / `_初稿` files)
 - **Output**: `.Knowledge/stock-docs/<Architecture Overview>_draft.md`
 
 **Sub-Agent Invocation**:
@@ -59,7 +59,7 @@
 
 **Purpose**: Converts PDF technical proposals or draft documents into the standardized "Final Draft Template" format, unifying the document structure for subsequent knowledge base ingestion.
 
-**How It Works**: Unstructured or heterogeneous documents (PDF/drafts) are normalized against the built-in final-draft template: core concept tables, business rules, key flows, configuration, error handling, and other standard sections are extracted; missing section markers are filled in; the output is a consistently structured `_final.md`. The final draft is the standard input for `f2s-ctx-build`, keeping knowledge-base entry structure uniform.
+**How It Works**: Unstructured or heterogeneous documents (PDF/drafts) are normalized against the built-in final-draft template: core concept tables, business rules, key flows, configuration, error handling, and other standard sections are extracted; missing section markers are filled in; the output is a consistently structured `_final.md`. The final draft is the standard input for `f2s-kb-build`, keeping knowledge-base entry structure uniform.
 
 **Use Cases**:
 - PDF technical proposals need conversion to Markdown
@@ -68,7 +68,7 @@
 
 **Relationships**:
 - **Prerequisite**: PDF document or draft document
-- **Next Step**: `f2s-ctx-build` (final draft imported into the knowledge base)
+- **Next Step**: `f2s-kb-build` (final draft imported into the knowledge base)
 - **Output**: `.Knowledge/stock-docs/<Document>_final.md`
 
 **Sub-Agent Invocation**:
@@ -83,7 +83,7 @@
 
 ---
 
-### `f2s-ctx-build`
+### `f2s-kb-build`
 
 **Purpose**: Synchronizes documents from `stock-docs/` (architecture, final drafts) into the knowledge base routing system, generating/updating topic files, the index, manifest-routing, and matchers.
 
@@ -117,11 +117,11 @@
 
 ---
 
-### `f2s-doc-add`
+### `f2s-kb-add`
 
 **Purpose**: Parses already-implemented capabilities (aggregated from multiple files) into the knowledge base. Suitable when code already exists but lacks documentation, or when multiple documents need to be imported into the knowledge base in a unified manner.
 
-**How It Works**: Aggregates capability descriptions from multiple scattered sources (code, config, loose docs) and runs the full "draft → final draft → topics/index/manifest" pipeline. Unlike `f2s-ctx-build`, the input differs: `ctx-build` is driven from a single existing final draft; `doc-add` aggregates many scattered sources first, then follows the same pipeline. It closes the gap of "implementation exists but documentation does not."
+**How It Works**: Aggregates capability descriptions from multiple scattered sources (code, config, loose docs) and runs the full "draft → final draft → topics/index/manifest" pipeline. Unlike `f2s-kb-build`, the input differs: `ctx-build` is driven from a single existing final draft; `doc-add` aggregates many scattered sources first, then follows the same pipeline. It closes the gap of "implementation exists but documentation does not."
 
 **Use Cases**:
 - Existing code needs knowledge base documentation
@@ -150,11 +150,11 @@
 
 ---
 
-### `f2s-ctx-rm`
+### `f2s-kb-rm`
 
 **Purpose**: Deletes corresponding knowledge topics and index mappings based on `stock-docs` documents. Only removes reference relationships in the knowledge base, not the source documents themselves.
 
-**How It Works**: The inverse of `f2s-ctx-build` — given a `stock-docs` document path, locate its task→topic rules in `manifest-routing.json`, the corresponding `matchers/<id>.json` shard, `topics/<topic>.md`, and entries in `index.md`, and remove those references one by one. If a topic has no remaining task references after deletion, remove that topic file. Source documents are left in place; the user may delete them physically if desired.
+**How It Works**: The inverse of `f2s-kb-build` — given a `stock-docs` document path, locate its task→topic rules in `manifest-routing.json`, the corresponding `matchers/<id>.json` shard, `topics/<topic>.md`, and entries in `index.md`, and remove those references one by one. If a topic has no remaining task references after deletion, remove that topic file. Source documents are left in place; the user may delete them physically if desired.
 
 **Use Cases**:
 - A document is deprecated and needs removal from the knowledge routing
@@ -186,7 +186,7 @@
 **Relationships**:
 - **Prerequisite**: PDF document
 - **Output**: `.Knowledge/req-docs/<Proposal>.md`
-- **Next Step** (recommended): `f2s-req-clarify` → `f2s-req-backend` → implement from the technical proposal MD via `implement-tech-design`; for knowledge base archival use `f2s-doc-final` → `f2s-ctx-build`
+- **Next Step** (recommended): `f2s-req-clarify` → `f2s-req-backend` → implement from the technical proposal MD via `implement-tech-design`; for knowledge base archival use `f2s-doc-final` → `f2s-kb-build`
 
 **Sub-Agent Invocation**:
 - `subAgent: false` (default): The main agent completes the full workflow
@@ -405,7 +405,7 @@
 - **Prerequisite**: None (can be triggered directly, or with zero-input inference)
 - **Next Step**: None
 - **Feature**: First outputs a knowledge base update outline, then writes only after user confirmation
-- **Difference from `f2s-ctx-build`**: `ctx-build` is driven from `stock-docs`; `kb-sync` infers from the conversation/code
+- **Difference from `f2s-kb-build`**: `ctx-build` is driven from `stock-docs`; `kb-sync` infers from the conversation/code
 
 **Sub-Agent Invocation**:
 - `subAgent: false` (default): The main agent completes inference and sync
@@ -525,14 +525,8 @@
 
 The following are not skill commands but rules activated by trigger words to guide Agent behavior.
 
-### `f2s-karpathy-guidelines`
-
-**Trigger Words**: `alwaysApply` (always on; no explicit trigger needed)
-
-**Purpose**: Flow2Spec's built-in Karpathy-style coding discipline to improve the quality of agent coding decisions.
-
-**How It Works**: Four behavioral constraints distilled from Andrej Karpathy's observations on common LLM coding mistakes, applied as an `alwaysApply` rule that implicitly governs all `f2s-*` skill runs: (1) think before coding (state assumptions; ask when unsure); (2) simplicity first (minimum code to solve the problem); (3) surgical edits (touch only what must change; match existing style); (4) goal-driven execution (define verifiable success criteria, then iterate). When these guidelines conflict with mandatory `f2s-*` steps, the `f2s-*` steps win.
 
+---
 ---
 
 ### `f2s-task`
@@ -557,25 +551,8 @@ The following are not skill commands but rules activated by trigger words to gui
 
 ---
 
-### `stock-docs-vs-req-docs`
-
-**Trigger Words**: stock-docs, req-docs, implemented capability, where to put the technical proposal, PDF final draft
-
-**Purpose**: Distinguishes the boundary between the knowledge archival directory and the requirements implementation directory.
-
-**How It Works**: "Purpose isolation" to avoid mixing folders — `stock-docs/` holds archived existing knowledge (architecture, final drafts), consumed by `ctx-build` for ingestion into the knowledge base and **must not** be used directly as coding input; `req-docs/` holds implementation-facing requirements and technical proposals, consumed by the `implement-tech-design` rule to drive coding. Writers and readers are fully separated so "stock descriptions are not mistaken for coding contracts" and "implementation proposals are not mistaken for capability archival."
-
-**Directory Division**:
-
-| Directory | Purpose | When It Is Written |
-|-----------|---------|-------------------|
-| `stock-docs/` | Archival of existing knowledge (architecture, final drafts) | `f2s-doc-arch`, `f2s-doc-final`, `f2s-ctx-build` |
-| `req-docs/` | Requirements and technical proposals (driving implementation) | `f2s-req-backend`, `f2s-doc-pdf`, manual placement |
-
-**Use Cases**:
-- Unsure where a document should go
-- Need to clarify the division of labor between stock-docs and req-docs
 
+---
 ---
 
 ### `implement-tech-design`

package/docs/en/design-principles.md

@@ -100,9 +100,9 @@ graph LR
 
     D1["Architecture Docs"] -->|f2s-doc-arch| FIN["f2s-doc-final"]
     D2["PDF/draft"] -->|f2s-doc-final| FIN
-    FIN --> CTX["f2s-ctx-build"] --> K
+    FIN --> CTX["f2s-kb-build"] --> K
 
-    OLD["Existing Code/Docs"] -->|f2s-doc-add| K
+    OLD["Existing Code/Docs"] -->|f2s-kb-add| K
 
     NR["New Requirement"] --> CL["f2s-req-clarify"] --> BE["f2s-req-backend"]
     BE --> IMPL["Implement xxx technical design"] -->|auto-trigger implement-tech-design rule| K
@@ -259,7 +259,7 @@ git log .Knowledge/
 
   a3f1c2  f2s-kb-feat: add refund state machine routing
   b7e9d1  f2s-kb-fix: fix RestTemplate injection conventions
-  c2a8f0  f2s-ctx-build: onboard order service architecture docs
+  c2a8f0  f2s-kb-build: onboard order service architecture docs
   d5b3e9  f2s-kb-sync: consolidate payment retry queue design
 
   Code changes  +  Knowledge changes  →  same commit or adjacent commits
@@ -521,7 +521,7 @@ The same `.Knowledge/` drives all tools  ·  adding/removing tools does not affe
 ```
 Adding a topic                         Removing a topic
 ─────────────────────               ─────────────────────
-1. Write topics/xxx.md               f2s-ctx-rm stock-docs/xxx.md
+1. Write topics/xxx.md               f2s-kb-rm stock-docs/xxx.md
 2. Write matchers/m-xxx.json                  ↓
 3. Register in manifest-routing       Automatically cleans up topics/ + manifest
                                        + index references

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)
 
@@ -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
 

package/docs/en/usage-scenarios.md

@@ -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**
 

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`（规划 + 实现，始终创建任务清单）

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

@@ -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）
 
@@ -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` 适合会话结束时的即时沉淀。
 
 ### 日常维护
 

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

@@ -8,9 +8,9 @@
 |---|---|---|
 | `/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` | 基于澄清结果生成后端技术方案文档 | 需求与方案 |
@@ -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 调用**：
 
@@ -474,7 +474,7 @@
 - **前置**：无（可直接触发，或零输入推断）
 - **后续**：无
 - **特点**：先输出知识库更新大纲，用户确认后才写入
-- **与 `f2s-ctx-build` 区别**：`ctx-build` 从 `stock-docs` 驱动，`kb-sync` 从会话/代码推断
+- **与 `f2s-kb-build` 区别**：`ctx-build` 从 `stock-docs` 驱动，`kb-sync` 从会话/代码推断
 
 **子 agent 调用**：
 
@@ -619,14 +619,8 @@
 
 以下不是技能命令，而是通过触发词激活的规则，用于辅助指导 Agent 的行为。
 
-### `f2s-karpathy-guidelines`
-
-**触发词**：`alwaysApply`（始终生效，无需显式触发）
-
-**作用**：Flow2Spec 内置的 Karpathy 式编码行为准则，约束 Agent 的编码决策质量。
-
-**工作原理**：从 Andrej Karpathy 对 LLM 写代码常见失误的观察中提炼四条行为约束，作为 `alwaysApply` 规则在所有 `f2s-*` 技能执行时隐式生效：① 先想清楚再写代码（假设要说清楚，不确定就问）；② 简单优先（用最少代码解决问题）；③ 手术式修改（只动该动的，风格对齐现有代码）；④ 目标驱动执行（先定义可验证的成功标准再循环迭代）。当这些准则与 `f2s-*` 强制步骤冲突时，以 `f2s-*` 为准。
 
+---
 ---
 
 ### `f2s-task`
@@ -653,28 +647,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`