@double-codeing/flow2spec 3.0.14 → 3.0.15

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 兰涛
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -5,12 +5,12 @@
 >
 > 🌐 **[中文](./README.md)** · 中 / EN
 
-🎬 **[Live Demo (English)](https://lands-1203.github.io/Flow2Spec/en/)** | **[中文演示](https://lands-1203.github.io/Flow2Spec/)** (13-slide HTML PPT, `←` `→` to navigate, `S` for presenter mode)
+🎬 **[Live Demo](https://lands-1203.github.io/Flow2Spec/)** (13-slide HTML PPT, `←` `→` to navigate, `S` for presenter mode)
 
 🔧 **Quick start**:
 
 ```bash
-npx @double-codeing/flow2spec@latest init
+npx @ctrip/flow2spec@latest init
 ```
 
 ---
@@ -68,7 +68,7 @@ Each task hits 1–4 topics, ~300 lines. Business constraints — Redis lock key
 **Minimum viable setup is an empty skeleton.**
 
 ```bash
-npx @double-codeing/flow2spec@latest init
+npx @ctrip/flow2spec@latest init
 ```
 
 1 minute generates the directory structure + routing config. Empty, ready to use. **Next requirement hits whichever area → you document that area.** No upfront investment needed.
@@ -94,20 +94,20 @@ Real data from a production repo running for 3 months:
 ## Documentation
 
 ### English
-- [Usage Guide](./docs/usage-guide.en.md) — skill chains, config details
-- [Commands Reference](./docs/commands-reference.en.md) — all f2s-* command reference
-- [Directory Conventions](./docs/directory-conventions.en.md)
-- [Architecture & Principles](./docs/architecture.en.md)
-- [Usage Scenarios](./docs/usage-scenarios.en.md)
-- [Design Principles](./docs/design-principles.en.md)
+- [Usage Guide](./docs/en/usage-guide.md) — skill chains, config details
+- [Commands Reference](./docs/en/commands-reference.md) — all f2s-* command reference
+- [Directory Conventions](./docs/en/directory-conventions.md)
+- [Architecture & Principles](./docs/en/architecture.md)
+- [Usage Scenarios](./docs/en/usage-scenarios.md)
+- [Design Principles](./docs/en/design-principles.md)
 
 ### 中文
-- [使用说明](./docs/Flow2Spec使用说明.md)
-- [命令说明](./docs/README-命令说明.md)
-- [目录与路径约定](./docs/README-目录与路径约定.md)
-- [体系与原理](./docs/README-体系与原理.md)
-- [使用案例·模拟对话](./docs/Flow2Spec-使用案例-模拟对话.md)
-- [设计说明](./docs/Flow2Spec-设计说明.md)
+- [使用说明](./docs/使用说明.md)
+- [命令说明](./docs/命令说明.md)
+- [目录与路径约定](./docs/目录与路径约定.md)
+- [体系与原理](./docs/体系与原理.md)
+- [使用案例·模拟对话](./docs/使用案例-模拟对话.md)
+- [设计说明](./docs/设计说明.md)
 
 ## License
 

package/README.md

@@ -5,12 +5,12 @@
 >
 > 🌐 **[English](./README.en.md)** · 中 / EN
 
-🎬 **[在线演示(中文)](https://lands-1203.github.io/Flow2Spec/)** | **[English Demo](https://lands-1203.github.io/Flow2Spec/en/)**（13 页 HTML PPT，`←` `→` 翻页，`S` 演讲者模式）
+🎬 **[在线演示](https://lands-1203.github.io/Flow2Spec/)**（13 页 HTML PPT，`←` `→` 翻页，`S` 演讲者模式）
 
 🔧 **快速体验**：
 
 ```bash
-npx @double-codeing/flow2spec@latest init
+npx @ctrip/flow2spec@latest init
 ```
 
 ---
@@ -69,7 +69,7 @@ topic 里，AI 不用从源码猜。
 **最小可用集是一个空骨架。**
 
 ```bash
-npx @double-codeing/flow2spec@latest init
+npx @ctrip/flow2spec@latest init
 ```
 
 1 分钟生成目录结构 + 路由配置，空的，直接跑。**下次需求命中哪块，写哪块**，不提前建设。
@@ -95,20 +95,20 @@ npx @double-codeing/flow2spec@latest init
 ## 详细文档
 
 ### 中文
-- [使用说明](./docs/Flow2Spec使用说明.md) — 技能链、配置详解
-- [命令说明](./docs/README-命令说明.md) — 所有 f2s-* 命令速查
-- [目录与路径约定](./docs/README-目录与路径约定.md)
-- [体系与原理](./docs/README-体系与原理.md)
-- [使用案例·模拟对话](./docs/Flow2Spec-使用案例-模拟对话.md)
-- [设计说明](./docs/Flow2Spec-设计说明.md)
+- [使用说明](./docs/使用说明.md) — 技能链、配置详解
+- [命令说明](./docs/命令说明.md) — 所有 f2s-* 命令速查
+- [目录与路径约定](./docs/目录与路径约定.md)
+- [体系与原理](./docs/体系与原理.md)
+- [使用案例·模拟对话](./docs/使用案例-模拟对话.md)
+- [设计说明](./docs/设计说明.md)
 
 ### English
-- [Usage Guide](./docs/usage-guide.en.md)
-- [Commands Reference](./docs/commands-reference.en.md)
-- [Directory Conventions](./docs/directory-conventions.en.md)
-- [Architecture & Principles](./docs/architecture.en.md)
-- [Usage Scenarios](./docs/usage-scenarios.en.md)
-- [Design Principles](./docs/design-principles.en.md)
+- [Usage Guide](./docs/en/usage-guide.md)
+- [Commands Reference](./docs/en/commands-reference.md)
+- [Directory Conventions](./docs/en/directory-conventions.md)
+- [Architecture & Principles](./docs/en/architecture.md)
+- [Usage Scenarios](./docs/en/usage-scenarios.md)
+- [Design Principles](./docs/en/design-principles.md)
 
 ## 协议
 

package/cli.js

@@ -58,7 +58,7 @@ init 会:
   5. 每次 init 将包内 templates/knowledge/index.md 复制到 .Knowledge/template/index.template.md，供 f2s-kb-upgrade 技能与 .Knowledge/index.md 对照；不自动改写 index.md。（「知识库升级」指 f2s-kb-upgrade 技能，init 本身不是升级命令。）
   6. 规则与技能在各 agent 配置根加载；其他模版类文件在 .Knowledge/template/ 等目录。
 
-更多说明见 README.md 或 docs/Flow2Spec使用说明.md
+更多说明见 README.md 或 docs/使用说明.md
 `;
 
 if (sub === "--help" || sub === "-h" || !sub) {
@@ -324,7 +324,7 @@ ${indexLine}
 ${configLine}
 ${lines.join("\n")}
 
-建议阅读 README 或 docs/Flow2Spec使用说明.md，按「规则在配置根、文档在 .Knowledge」的方式使用。
+建议阅读 README 或 docs/使用说明.md，按「规则在配置根、文档在 .Knowledge」的方式使用。
 `);
     })
     .catch((e) => {

package/docs/.mermaid-cache.json

@@ -0,0 +1,49 @@
+{
+  "设计说明.md": [
+    {
+      "content": "graph TB\n    subgraph MC[\"Memory Coding · 仓内四环\"]\n        KR[\"知识环 .Knowledge/\"]\n        TR[\"任务环 .task/\"]\n        RR[\"规则环 rules\"]\n        SR[\"技能环 f2s-*\"]\n    end\n    SR -->|\"维护 ↑\"| KR\n    RR -->|\"读与做 ↓\"| KR\n    TR -.->|\"并列，不在 .Knowledge 内\"| KR",
+      "hash": "fae76e2801d0",
+      "marker": "MERMAID_fae76e2801d0"
+    },
+    {
+      "content": "graph TB\n    subgraph H[\"横读 · 渐进式收窄\"]\n        L0[\"L0 manifest-routing\"]\n        L1[\"L1 matchers 分片\"]\n        L2[\"L2 topics 摘要\"]\n        L3[\"L3 stock-docs / req-docs\"]\n        L0 --> L1 --> L2 --> L3\n    end\n    subgraph V[\"纵链 · topicDependencies\"]\n        T1[\"通用约定\"]\n        T2[\"子域边界\"]\n        T3[\"端上白名单\"]\n        T4[\"本域细则\"]\n        T1 --> T2 --> T3 --> T4\n    end\n    L2 --- V",
+      "hash": "2c3581e0ec89",
+      "marker": "MERMAID_2c3581e0ec89"
+    },
+    {
+      "content": "graph LR\n    subgraph K[\".Knowledge/  知识层\"]\n        K1[架构说明]\n        K2[技术方案]\n        K3[路由索引]\n    end\n\n    subgraph R[\"配置根  执行层\"]\n        R1[.cursor/rules/]\n        R2[.claude/rules/]\n        R3[.codex/AGENTS.md]\n    end\n\n    K -->|知识输入| AI[AI 工具]\n    R -->|规则约束| AI\n\n    note1[\"知识随项目迭代\"] -.-> K\n    note2[\"规则随工具升级\"] -.-> R",
+      "hash": "048f705f3b6a",
+      "marker": "MERMAID_048f705f3b6a"
+    },
+    {
+      "content": "graph LR\n    T[任务] --> M[manifest-routing\\n读路由表]\n    M -->|关键词匹配| MT[matchers/xxx.json\\n只读这一个分片]\n    MT -->|命中| TP[topics/xxx.md]\n    TP --> V{缺口检查}\n    V -->|通过| ACT[执行]\n    V -->|不足| Q[向用户澄清]\n    M -->|未命中| FB[fallback-triage\\n结构化分诊]",
+      "hash": "a24148e2b009",
+      "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",
+      "hash": "6335fa6eda40",
+      "marker": "MERMAID_6335fa6eda40"
+    },
+    {
+      "content": "graph LR\n    SKILL[\"f2s-kb-feat / f2s-kb-fix\\nimplement-tech-design\"] -->|\"changeTracking: true\"| TJ[\".task/active/\\ntask.md · todo.json\"]\n    RP[\"f2s-req-plan\\n（始终创建）\"] --> TJ\n\n    TJ --> NS[新会话首条消息]\n    NS -->|关键词匹配| LD[\"加载剩余 checklist\\n+ linkedSkill 上下文\"]\n    LD --> RS[按原技能约束继续]",
+      "hash": "954431299027",
+      "marker": "MERMAID_954431299027"
+    },
+    {
+      "content": "graph TD\n    F[进入 fallback-triage] --> S1{路由是否命中?}\n    S1 -->|已命中但上下文不足| EXP[展开依赖主题\\n补齐后继续]\n    S1 -->|未命中| Q[询问用户:\\n这个领域文档是否已录入?]\n    Q -->|是| HINT[路由词条缺失\\n建议补路由]\n    Q -->|否| CHOICE[下钻源码\\n或补充 req-docs]\n    Q -->|不确定| STOP[停止执行\\n等待明确指令]",
+      "hash": "4318b3c68d8d",
+      "marker": "MERMAID_4318b3c68d8d"
+    },
+    {
+      "content": "graph LR\n    S1[步骤1: 素材汇总] -->|subAgent=true 可并行| SUB[子 agent]\n    SUB -->|只读，不落盘| S2\n\n    S2[步骤2: 输出大纲\\n用户确认] -->|必须主 agent| USER[用户]\n    USER -->|确认| S3\n\n    S3[步骤3: 落盘] -->|subAgent=true 可并行| SUB2[子 agent]",
+      "hash": "a2564dc94095",
+      "marker": "MERMAID_a2564dc94095"
+    },
+    {
+      "content": "graph LR\n    T[触发 f2s-kb-sync] --> O[输出更新大纲]\n    O --> U{用户确认}\n    U -->|确认| W[写入 .Knowledge/]\n    U -->|修改| O\n    U -->|取消| STOP[不写入]",
+      "hash": "07d348a75406",
+      "marker": "MERMAID_07d348a75406"
+    }
+  ]
+}

package/docs/.sync-mapping.json

@@ -0,0 +1,59 @@
+{
+  "Flow2Spec-设计说明.md": {
+    "hash": ""
+  },
+  "体系与原理.md": {
+    "dedup_reuse": true,
+    "doc_token": "MJ3ddOEadoSalLxup2tctXC3nSh",
+    "hash": "36d6d00cae030bf24d8b669471ae4c27333ab0a3f59f73871b87ea271c35f112",
+    "last_sync": "2026-05-21T11:32:28",
+    "node_token": "JPX7wpAUxilS43kP31XclcJfnYb",
+    "space_id": "7516389318031998979",
+    "title": "体系与原理"
+  },
+  "使用案例-模拟对话.md": {
+    "doc_token": "PtAyd2CPloSUjcxZu5Rco7ylnRd",
+    "hash": "35fe556b103e683f1fcf15de79a68d775430c0fb9ebe456b8e1d326e8b3371c0",
+    "last_sync": "2026-05-21T11:31:57",
+    "node_token": "BzpzwlXVIiiJjNkqjDBcVVmGngu",
+    "space_id": "7516389318031998979",
+    "title": "Flow2Spec 使用案例（模拟对话）",
+    "url": "https://trip.larkenterprise.com/docx/PtAyd2CPloSUjcxZu5Rco7ylnRd"
+  },
+  "使用说明.md": {
+    "doc_token": "ULCudGycqo8G7gx6Jm9cxaD8nPf",
+    "hash": "8b627acc009e0405785f400bb6a9f250fdf93ffcd15a992c22bb5b4cc52d90e2",
+    "last_sync": "2026-05-21T11:32:24",
+    "node_token": "XpLYw8SCri3zzskG9Xhc3Ir1nsf",
+    "space_id": "7516389318031998979",
+    "title": "Flow2Spec 使用说明",
+    "url": "https://trip.larkenterprise.com/docx/ULCudGycqo8G7gx6Jm9cxaD8nPf"
+  },
+  "命令说明.md": {
+    "doc_token": "SfrGd4Fj2odWvsxj944cINqQnWh",
+    "hash": "7498e8d5b551db305dd1fa348044f66ffcdde77372f0ab963e6163e022a15186",
+    "last_sync": "2026-05-21T11:32:40",
+    "node_token": "AyE5wuPhoi4pPMkqxLgc4v53nfb",
+    "space_id": "7516389318031998979",
+    "title": "工作流与技能说明",
+    "url": "https://trip.larkenterprise.com/docx/SfrGd4Fj2odWvsxj944cINqQnWh"
+  },
+  "目录与路径约定.md": {
+    "dedup_reuse": true,
+    "doc_token": "KPebdJeyKoxFxLx66lgcmvVNnkc",
+    "hash": "c4fcff4abf8290910840a6448e5b49793be47c9e37a7b0d737095f0942444812",
+    "last_sync": "2026-05-21T11:32:44",
+    "node_token": "FNaCwSIGNiye0wkp9mEc76ohn1g",
+    "space_id": "7516389318031998979",
+    "title": "目录与路径约定"
+  },
+  "设计说明.md": {
+    "doc_token": "DSD8duoqwoIb2XxsspKcKirinjg",
+    "hash": "440310cf3c35a80b4ba21ce15d6e7d07e754169ab1fa2de92756362a10b12f6e",
+    "last_sync": "2026-05-21T11:32:09",
+    "node_token": "SsZJwXuNyiGPcBk4ftdcIrIhnwb",
+    "space_id": "7516389318031998979",
+    "title": "Flow2Spec 设计说明",
+    "url": "https://trip.larkenterprise.com/docx/DSD8duoqwoIb2XxsspKcKirinjg"
+  }
+}

package/docs/en/README.md

@@ -0,0 +1,12 @@
+# English documentation
+
+Product docs in English live under `docs/en/`. Chinese docs are in `docs/` (repository root of this folder).
+
+| Document | Chinese counterpart |
+| --- | --- |
+| [usage-guide.md](./usage-guide.md) | [使用说明.md](../使用说明.md) |
+| [commands-reference.md](./commands-reference.md) | [命令说明.md](../命令说明.md) |
+| [directory-conventions.md](./directory-conventions.md) | [目录与路径约定.md](../目录与路径约定.md) |
+| [architecture.md](./architecture.md) | [体系与原理.md](../体系与原理.md) |
+| [usage-scenarios.md](./usage-scenarios.md) | [使用案例-模拟对话.md](../使用案例-模拟对话.md) |
+| [design-principles.md](./design-principles.md) | [设计说明.md](../设计说明.md) |

package/docs/{architecture.en.md → en/architecture.md}

@@ -1,24 +1,61 @@
-[中文](./README-体系与原理.md) | [English](./architecture.en.md)
+[中文](../体系与原理.md) | [English](./architecture.md)
 
 # Architecture & Principles
 
-Flow2Spec's goal is to separate "business knowledge curation" from "Agent capability loading":
+Flow2Spec separates "business knowledge curation" from "Agent capability loading", and uses **Memory Coding** to persist "what must be remembered" as versioned Git assets.
 
-- **Knowledge layer**: `.Knowledge` (documents and index)
-- **Execution layer**: config root `rules/skills` (natively loaded by each tool)
+- **Knowledge ring** (`.Knowledge/`): documents and machine-readable routing (multi-layer, see below)
+- **Task ring** (`.task/`): cross-session task checklists
+- **Rules ring** (tool `rules` / `AGENTS.md`): how to **read** and **act**
+- **Skills ring** (`f2s-*`): maintain knowledge and trigger workflows
+
+> Flow2Spec is not "just a knowledge base." All four rings are Memory Coding; the two-layer table below is the **knowledge ring vs tool-side execution** lifecycle split.
+
+---
+
+## 1. Memory Coding and Four Rings
+
+**Memory Coding**: encode durable context into the **committed repo**—not private model memory, not chat-only repetition, not whole-repo vector guessing.
+
+Four rings in the repo (do not collapse rules + skills into a single "third ring"):
+
+| Ring | Location | Stores |
+| --- | --- | --- |
+| **Knowledge** | `.Knowledge/` | Routing, topics, stock/req docs (§2 layers) |
+| **Task** | `.task/` | `todo.json`, checklists, user todos |
+| **Rules** | `.cursor/.claude/.codex` rules, `AGENTS.md` | Read order, gap gates, execution constraints |
+| **Skills** | config root `skills/*/SKILL.md` | `f2s-kb-feat/fix/sync`, etc. |
+
+---
+
+## 2. Multi-Layer Memory Inside the Knowledge Ring
+
+`.Knowledge/` is not a flat pile of Markdown. It combines **horizontal narrowing** (progressive routing) and **vertical chaining** (topic dependencies):
+
+| Layer | Path / mechanism | Stores | Typical read |
+| --- | --- | --- | --- |
+| **L0 routing** | `manifest-routing.json` | task→topic, `topicDependencies`, `topicPaths` | 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 |
+| **Vertical chain** | `topicDependencies` | Common → subdomain → whitelist → domain rules | **expand** stacks layers |
+
+The pipeline `match → expand → verify → act` operates on L0–L2 (and L3 when needed). Topic-level dependencies are declared once and shared by all tasks.
+
+`index.md` is human navigation only; it does not replace the machine-readable chain.
 
 ---
 
-## 1. Two-Layer Structure
+## 3. Knowledge Layer vs Execution Layer (Two Layers)
 
 | Layer | Location | Role |
 | --- | --- | --- |
-| Knowledge layer | `.Knowledge/` | Stores business documents, index, routing |
-| Execution layer | `.cursor/.claude/.codex` | Stores rules and skill entry points |
+| Knowledge layer (knowledge ring) | `.Knowledge/` | Business docs, index, routing (§2 layers) |
+| Execution layer (rules + skills rings) | `.cursor/.claude/.codex` | Rules and skill entry points |
 
 ---
 
-## 2. Progressive Reading
+## 4. Progressive Reading
 
 The recommended unified order:
 
@@ -35,7 +72,7 @@ Codex does not read the `rules/` directory; execution constraints are carried th
 
 ---
 
-## 3. Key Chains
+## 5. Key Chains
 
 - Documentation curation chain: `f2s-doc-arch` -> `f2s-doc-final` -> `f2s-ctx-build`
 - Implementation chain: `.Knowledge/req-docs/*.md` -> `implement-tech-design` -> code
@@ -46,13 +83,13 @@ Codex does not read the `rules/` directory; execution constraints are carried th
 
 ---
 
-## 4. Agent Execution Model
+## 6. Agent Execution Model
 
 Flow2Spec controls execution behavior through two fields in the project root `flow2spec.config.json`: `subAgent` and `switchAgentVerification`.
 
-**How the Agent reads the above truth values**: multi-end prompts + **Read** as authority, see [usage-guide.en.md § 1 (the only detailed table)](./usage-guide.en.md); design summary see [design-principles.en.md § 4, 5.1](./design-principles.en.md).
+**How the Agent reads the above truth values**: multi-end prompts + **Read** as authority, see [usage-guide.md § 1 (the only detailed table)](./usage-guide.md); design summary see [design-principles.md § 4, 5.1](./design-principles.md).
 
-### 4.1 Primary/Sub Agent Responsibility Division Principle
+### 6.1 Primary/Sub Agent Responsibility Division Principle
 
 **`subAgent: false` (default)**: All `f2s-*` skills execute sequentially within the primary agent, no parallel decomposition.
 
@@ -65,7 +102,7 @@ Flow2Spec controls execution behavior through two fields in the project root `fl
 
 The decomposition boundaries for sub-agents are progressively defined by each `f2s-*` skill body (e.g., thresholds for module count, document count, code line count). **There is currently no unified stage table at the template layer**; the skill body takes precedence.
 
-### 4.2 Verification Ownership Principle
+### 6.2 Verification Ownership Principle
 
 **Default (whoever writes to disk verifies)**: Verification after write-to-disk or changes is performed within the agent that wrote to disk. If a sub-agent wrote, the sub-agent self-verifies; if the primary agent wrote, the primary agent self-verifies.
 
@@ -83,7 +120,7 @@ Cross-verification rules:
 
 Design intent: Cross-verification introduces an external perspective, reducing the blind spots in the writer's self-verification, but increases execution overhead. It is therefore an explicit opt-in rather than the default behavior.
 
-### 4.3 Change Tracking (changeTracking)
+### 6.3 Change Tracking (changeTracking)
 
 `changeTracking` is a third dimension independent of `subAgent` / `switchAgentVerification`. It controls whether the skill automatically creates a task checklist that can be continued across sessions during execution.
 
@@ -104,7 +141,7 @@ Design intent: Cross-verification introduces an external perspective, reducing t
 
 ---
 
-## 5. Design Benefits
+## 7. Design Benefits
 
 1. Share the same business knowledge source across tools
 2. Does not break the rule loading conventions of Claude/Cursor/Codex
@@ -114,9 +151,9 @@ Design intent: Cross-verification introduces an external perspective, reducing t
 
 ---
 
-## 6. Related Documents
+## 8. Related Documents
 
-- [Usage Guide](./usage-guide.en.md)
-- [Commands Reference](./commands-reference.en.md)
-- [Directory Conventions](./directory-conventions.en.md)
-- [Usage Scenarios](./usage-scenarios.en.md)
+- [Usage Guide](./usage-guide.md)
+- [Commands Reference](./commands-reference.md)
+- [Directory Conventions](./directory-conventions.md)
+- [Usage Scenarios](./usage-scenarios.md)

package/docs/{commands-reference.en.md → en/commands-reference.md}

@@ -1,4 +1,4 @@
-[中文](./README-命令说明.md) | [English](./commands-reference.en.md)
+[中文](../命令说明.md) | [English](./commands-reference.md)
 
 # Workflow and Skill Reference
 
@@ -153,19 +153,17 @@
 
 **Purpose**: Converts PDF technical proposals to Markdown format, saves to `req-docs/`, and can supplement the process description.
 
-**How It Works**: Targets the step before "implement from a proposal" — extracts structured content from the PDF (API definitions, data models, sequence flows, etc.) into Markdown under `req-docs/`. Unlike `f2s-doc-final`, the destination and use differ: `doc-pdf` writes to `req-docs/` for consumption by the `implement-tech-design` rule to drive coding; `doc-final` writes to `stock-docs/` for ingestion via `ctx-build`.
+**How It Works**: Extracts structured content from the PDF (API definitions, data models, sequence flows, etc.) into Markdown under `req-docs/` for editing and follow-up with `f2s-req-clarify` / `f2s-req-backend`. Unlike `f2s-doc-final`, `doc-pdf` writes to `req-docs/`; `doc-final` writes to `stock-docs/` for `ctx-build`. **Not recommended** as a shortcut for "PDF straight to coding" without clarification and a backend technical proposal.
 
 **Use Cases**:
-- A PDF technical proposal needs to be implemented
-- Historical PDF documents need to be managed
-- Cross-team deliverables are in PDF format and need conversion
+- Cross-team deliverables are in PDF format and need conversion to editable Markdown
+- Historical PDF proposals need to live under `req-docs/`
+- Provide a readable draft before `f2s-req-clarify` / `f2s-req-backend`
 
 **Relationships**:
 - **Prerequisite**: PDF document
 - **Output**: `.Knowledge/req-docs/<Proposal>.md`
-- **Next Step**:
-  - 1. If it is a requirement to implement: provide the converted proposal path with instructions "implement according to the technical proposal", driven by the `implement-tech-design` rule
-  - 2. If it is for knowledge base archival: follow the final-draft conversion flow `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-ctx-build`
 
 **Sub-Agent Invocation**:
 - `subAgent: false` (default): The main agent completes the full workflow
@@ -594,7 +592,7 @@ Controlled via `flow2spec.config.json` at the project root (all fields default t
 
 ### How Different Products "See" the Configuration (use with the field table below)
 
-`subAgent` and similar fields are written to the **on-disk JSON**; products do not guarantee automatic file opening. Therefore, multi-layered hints are provided via **Cursor rules / Claude hooks / Codex AGENTS snapshot table / knowledge base `config-precheck` summary**, but **the authoritative source remains `Read("flow2spec.config.json")`** (design rationale in [design-principles.en.md — Agent Orchestration § 5.1](./design-principles.en.md); talk / deck pacing in [intro deck HTML](../presentations/flow2spec-intro-public-en/index.html), config section). **The full path and table are maintained in one place**: [usage-guide.en.md Sec. 1, `f2s-*` and `flow2spec.config.json`](./usage-guide.en.md).
+`subAgent` and similar fields are written to the **on-disk JSON**; products do not guarantee automatic file opening. Therefore, multi-layered hints are provided via **Cursor rules / Claude hooks / Codex AGENTS snapshot table / knowledge base `config-precheck` summary**, but **the authoritative source remains `Read("flow2spec.config.json")`** (design rationale in [design-principles.md — Agent Orchestration § 5.1](./design-principles.md); talk / deck pacing in [intro deck HTML](../../presentations/flow2spec-intro-public-en/index.html) (internal); Chinese source in `flow2spec-intro-draft`, config section). **The full path and table are maintained in one place**: [usage-guide.md Sec. 1, `f2s-*` and `flow2spec.config.json`](./usage-guide.md).
 
 ### `subAgent` Field
 
@@ -632,20 +630,20 @@ A nested object, with each skill independently controlled:
 
 > `f2s-req-plan` is not constrained by this configuration; it always creates a task checklist. Legacy boolean values (`"changeTracking": true/false`) are backward-compatible and automatically expand to all three sub-fields on/off.
 
-For full principles and design intent, see [architecture.en.md Sec. 4. Agent Execution Model](./architecture.en.md).
+For full principles and design intent, see [architecture.md Sec. 4. Agent Execution Model](./architecture.md).
 
 ---
 
 ## 7) Quick Reference
 
-For typical work scenarios and full workflows, see [Usage Guide § 3. Typical Workflows](./usage-guide.en.md).
+For typical work scenarios and full workflows, see [Usage Guide § 3. Typical Workflows](./usage-guide.md).
 
-For a complete directory description, see [Directory Conventions](./directory-conventions.en.md).
+For a complete directory description, see [Directory Conventions](./directory-conventions.md).
 
 ---
 
 Related Documents:
-- [Usage Guide](./usage-guide.en.md)
-- [Directory Conventions](./directory-conventions.en.md)
-- [Architecture](./architecture.en.md)
-- [Usage Scenarios](./usage-scenarios.en.md)
+- [Usage Guide](./usage-guide.md)
+- [Directory Conventions](./directory-conventions.md)
+- [Architecture](./architecture.md)
+- [Usage Scenarios](./usage-scenarios.md)

package/docs/{design-principles.en.md → en/design-principles.md}

@@ -1,4 +1,4 @@
-[中文](./Flow2Spec-设计说明.md) | [English](./design-principles.en.md)
+[中文](../设计说明.md) | [English](./design-principles.md)
 
 # Flow2Spec Design Principles
 
@@ -21,6 +21,25 @@ Team experience         ──┘    reinterpreted  ├── topics/
 
 ## Core Design
 
+### 0. Memory Coding and Four Rings
+
+**Memory Coding**: encode durable context into the **committed repository** (PR-reviewable), not private model memory or chat-only context.
+
+Four rings in the repo (rules ring and skills ring are separate—do not merge):
+
+| Ring | Location | Role |
+| --- | --- | --- |
+| Knowledge | `.Knowledge/` | Routing, topics, stock/req docs |
+| Task | `.task/` | Cross-session continuation, user todos |
+| Rules | Tool `rules` / `AGENTS.md` | How to read and act |
+| Skills | `f2s-*` / `skills/` | Maintain KB, trigger workflows |
+
+Flow2Spec delivers the **Memory Coding persistence and maintenance loop**, not "another RAG knowledge base."
+
+### 0.1 Knowledge Ring: Multi-Layer Memory
+
+Inside the knowledge ring: **horizontal narrowing** (L0 manifest → L1 matchers → L2 topics → L3 long docs) plus **vertical chaining** (`topicDependencies`: common → subdomain → whitelist → domain). The `match → expand → verify → act` pipeline operates on these layers; see [architecture.md §4](./architecture.md).
+
 ### 1. Separation of Knowledge and Rules
 
 ```mermaid
@@ -80,7 +99,7 @@ graph LR
     CMT -->|"Not in KB, remind\n-> kb-sync/kb-feat"| K
 
     D1["Architecture Docs"] -->|f2s-doc-arch| FIN["f2s-doc-final"]
-    D2["PDF Proposal"] -->|f2s-doc-pdf| FIN
+    D2["PDF/draft"] -->|f2s-doc-final| FIN
     FIN --> CTX["f2s-ctx-build"] --> K
 
     OLD["Existing Code/Docs"] -->|f2s-doc-add| K
@@ -463,7 +482,7 @@ Session context itself is an information source  ·  no need for users to organi
 | **Codex `AGENTS.md` + `renderProjectConfigBlock`** | Top-level **Read** hard constraint + **init snapshot table** (if inconsistent with disk, Read takes precedence). |
 | **Knowledge base `config-precheck` topic** | When routing hits, provides only **summary** and a pointer to the Codex full text, **not** a substitute for Read JSON. |
 
-**Authority remains** the **Read** result of the project-root JSON; each layer is a prompt, not a second source of truth. For the complete operational table and paths, see **[Usage Guide § 1. `f2s-*` and `flow2spec.config.json`](./usage-guide.en.md)**.
+**Authority remains** the **Read** result of the project-root JSON; each layer is a prompt, not a second source of truth. For the complete operational table and paths, see **[Usage Guide § 1. `f2s-*` and `flow2spec.config.json`](./usage-guide.md)**.
 
 #### 6. Skills don't restate unified entry rules, only reference them
 
@@ -593,7 +612,7 @@ Best suited when: has scale · long-term iteration · multi-tool or multi-person
 
 ## Related Documents
 
-- [Usage Guide](./usage-guide.en.md)
-- [Commands Reference](./commands-reference.en.md)
-- [Architecture](./architecture.en.md)
-- [Usage Scenarios](./usage-scenarios.en.md)
+- [Usage Guide](./usage-guide.md)
+- [Commands Reference](./commands-reference.md)
+- [Architecture](./architecture.md)
+- [Usage Scenarios](./usage-scenarios.md)

package/docs/{directory-conventions.en.md → en/directory-conventions.md}

@@ -1,11 +1,14 @@
-[中文](./README-目录与路径约定.md) | [English](./directory-conventions.en.md)
+[中文](../目录与路径约定.md) | [English](./directory-conventions.md)
 
 # Directory and Path Conventions
 
 ## Core Boundary
 
-- `.Knowledge/`: Business knowledge documents and index only
-- `Config Root` (`.cursor/.claude/.codex`): Rules and skill entry points
+- `.Knowledge/`: **Knowledge ring** — business docs and machine-readable routing ([architecture.md §2](./architecture.md))
+- `.task/`: **Task ring** — change tracking (not inside `.Knowledge/`)
+- `Config Root` (`.cursor/.claude/.codex`): **Rules ring + skills ring**
+
+See [architecture.md §1](./architecture.md) for Memory Coding four rings.
 
 ---
 
@@ -13,13 +16,15 @@
 
 | Path | Responsibility |
 | --- | --- |
-| `.Knowledge/stock-docs/` | Architecture, final drafts, reference documents |
-| `.Knowledge/req-docs/` | Requirement clarification, technical proposals |
-| `.Knowledge/topics/` | Topic routing documents (for rules and workflow execution) |
+| `docs/` | Product docs (**Chinese**): usage guide, commands reference, design principles, etc. |
+| `docs/en/` | Product docs (**English**): six paired documents; see [README.md](./README.md) |
+| `.Knowledge/stock-docs/` | **L3** Architecture, final drafts, reference documents |
+| `.Knowledge/req-docs/` | **L3** Requirement clarification, technical proposals |
+| `.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` | Machine-readable routing skeleton (task/topic/dependencies) |
-| `.Knowledge/matchers/*.json` | Keyword fragments (`id/includeAny`), directly linked by `manifest-routing.taskToTopicRules[].matcherPath` |
+| `.Knowledge/manifest-routing.json` | **L0** Machine-readable routing skeleton (task/topic/`topicDependencies`) |
+| `.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 |
 | `Config Root/rules/` | Rule files (Cursor `.mdc`, Claude `.md`) |
@@ -28,7 +33,7 @@
 | `.codex/AGENTS.md` | Codex unified entry point and loading instructions |
 | `flow2spec.config.json` | Project root configuration, controls `subAgent`, `switchAgentVerification`, `changeTracking` (nested object with `feat` / `fix` / `implement` sub-items) |
 
-> See [Usage Guide Section 1](./usage-guide.en.md) for multi-platform references and path tables (detail maintained in a single table); **the authoritative source remains `Read(flow2spec.config.json)`**.
+> See [Usage Guide Section 1](./usage-guide.md) for multi-platform references and path tables (detail maintained in a single table); **the authoritative source remains `Read(flow2spec.config.json)`**.
 
 ---
 
@@ -43,7 +48,7 @@
 
 ## Related Documents
 
-- [Usage Guide](./usage-guide.en.md)
-- [Commands Reference](./commands-reference.en.md)
-- [Architecture](./architecture.en.md)
-- [Usage Scenarios](./usage-scenarios.en.md)
+- [Usage Guide](./usage-guide.md)
+- [Commands Reference](./commands-reference.md)
+- [Architecture](./architecture.md)
+- [Usage Scenarios](./usage-scenarios.md)